目次

リリースノート

過去のリリースノート

Changelogs

プロダクトに貢献するには（バグ報告、パッチ投稿、メーリングリスト）

Asakusa Framework 入門

Asakusa Framework概観

Asakusa Framework スタートガイド

開発の流れ

アプリケーションの実装 - Asakusa Data Model

DMDLスタートガイド

DMDLユーザーガイド

DMDL開発者ガイド

アプリケーションの実装 - Asakusa DSL

Asakusa DSLスタートガイド

Asakusa DSLユーザーガイド

演算子リファレンス

多相データフロー

ビューAPI

Asakusa DSL開発者ガイド

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

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

テストドライバーユーザーガイド

Excelによるテストデータ定義

JSONによるテストデータ定義

テストドライバー開発者ガイド

データの直接入出力 - Direct I/O

Direct I/O スタートガイド

Direct I/O ユーザーガイド

Direct I/O CSV

Direct I/O TSV

Direct I/O formatted text

Direct I/O JSON

Direct I/O line

Direct I/O sequence file

Direct I/O Hive

Direct I/O コマンドラインツールユーザーガイド

Direct I/O CLI ユーザーガイド

外部システムとの連携 - WindGate

WindGateスタートガイド

WindGateユーザーガイド

WindGateに関するログ一覧

WindGate開発者ガイド

WindGate TSV

アプリケーションの実行 - YAESS

YAESSスタートガイド

YAESSユーザーガイド

ジョブ実行クラスターの振り分け

YAESS JobQueue

YAESSに関するログ一覧

コマンドラインインターフェース - Asakusa CLI

Asakusa CLI ユーザーガイド

開発環境の整備 - Asakusa Gradle Plugin

Asakusa Gradle Plugin ユーザーガイド

Asakusa Gradle Plugin リファレンス

開発環境マイグレーションガイド

Asakusa Gradle Plugin マイグレーションガイド

Asakusa Gradle Plugin バージョン 0.10系 の変更点

Asakusa Gradle Plugin バージョン 0.9系 の変更点

Asakusa Gradle Plugin バージョン 0.8系 の変更点

過去の開発環境マイグレーションガイド

開発環境のJava

IntelliJ IDEAの利用

Asakusa Gradle Plugin:非推奨機能

運用環境の整備

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

システム構成の検討

Hadoopパラメータの設定

実行時プラグインのデプロイ

運用環境マイグレーションガイド

Amazon EMR上でAsakusa Frameworkを利用する

Asakusa FrameworkとHiveを連携して利用する

ユーティリティツールユーザーガイド

Asakusa on Spark

Asakusa on Spark ユーザガイド

Asakusa on Sparkの最適化設定

Asakusa on Spark リファレンス

Asakusa on Spark Iterative Extensions

リリースノート

過去のリリースノート

Changelogs

Asakusa on M³BP

Asakusa on M³BPユーザーガイド

Asakusa on M³BPの最適化設定

Asakusa on M³BPリファレンス

リリースノート

Changelogs

Asakusa Vanilla

Asakusa Vanilla ユーザーガイド

Asakusa Vanilla リファレンス

Asakusa on MapReduce

Asakusa on MapReduce リファレンス

エミュレーションモードによるアプリケーションテスト

Asakusa on MapReduce DSLの可視化

開発環境にHadoopを導入する

MapReduceタスクの最適化設定

ライブラリキャッシュの設定

プロダクトについて

対応プラットフォーム

試験的機能

非推奨機能

ライセンス

ドキュメントの方針

ドキュメントビルド環境の構築

ドキュメンテーションの構成

ToDo

リリースノート

Asakusa Frameworkのリリースノートです。すべての変更点は Changelogs を参照してください。

Release 0.10.3

Jun 12, 2019

Asakusa Framework 0.10.3 documentation [https://docs.asakusafw.com/0.10.3/release/ja/html/index.html]

新機能と主な変更点

Direct I/O JSON (試験的機能)

Direct I/OでJSON形式を持つテキストファイルを読み書きするための汎用的な機能を提供する Direct I/O JSON を追加しました。

Direct I/O JSONでは JSON Lines [http://jsonlines.org/] と呼ばれる、JSONの1レコードを1行で格納し、レコード間を改行で区切る形式もサポートしています。 JSON Lines形式の入力ファイルは分割して処理を行うことができるため、通常のJSON形式に比べて高速にファイルの入力処理を実行できる可能性があります。

Direct I/O JSONで出力するファイルの形式は、JSON Lines形式となります。

詳しくは、以下のドキュメントを参照してください。

Direct I/O JSON

その他の変更点

ロギング演算子 上限境界の無い型引数を定義することができない不具合の修正

Direct I/O Hive 指定可能なHive実行ライブラリのバージョンに、バージョン1系(例: 1.2.2 )に加えてバージョン2系(例: 2.3.4 )を追加

Direct I/O Hive 実行ログに表示される入出力データのカウント情報に誤った値が表示される不具合の修正（一部制約事項があります。詳しくは Direct I/O ユーザーガイド - 入出力データのカウント情報 を参照してください）

Asakusa on Spark Direct I/Oの出力ファイル名のパターンに「ランダムな値」を指定することができない不具合の修正

Asakusa on M3BP Hadoopバージョン3系など一部のHadoop環境でネイティブライブラリの検出に失敗する不具合の修正

その他、細かな機能改善およびバグフィックスが含まれます。すべての変更点は Changelogs を参照してください。

互換性に関して

本リリースでは過去バージョンとの互換性に関する特別な情報はありません。

Release 0.10.2

Sep 26, 2018

Asakusa Framework 0.10.2 documentation [https://docs.asakusafw.com/0.10.2/release/ja/html/index.html]

新機能と主な変更点

ビューAPIを以下の演算子に使用した場合に正しくコンパイルされないことがある不具合の修正

マスタ確認演算子

マスタ結合演算子

マスタ分岐演算子

マスタつき更新演算子

Direct I/O の以下のフォーマットについて、長い文字列を含むデータを入力した場合にパースに失敗することがある不具合の修正

Direct I/O formatted text

Direct I/O line

Direct I/O TSV

broadcast joinアルゴリズムやビューAPIを使った結合演算子を含むデータフローが、まれなケースで循環参照を引き起こしコンパイルエラーとなる不具合の修正

テストドライバーユーザーガイド 、およびテスト機能に関連する各ドキュメントの整理と改訂

Asakusa Framework チュートリアル [https://docs.asakusafw.com/basic-tutorial/0.10/release/ja/html/index.html] と Shafuのドキュメント [https://docs.asakusafw.com/jinrikisha/ja/html/shafu.html] を Shafu バージョン 0.7.0 の機能に合わせて改訂

その他、細かな機能改善およびバグフィックスが含まれます。すべての変更点は Changelogs を参照してください。

互換性に関して

本リリースでは過去バージョンとの互換性に関する特別な情報はありません。

Release 0.10.1

Jun 27, 2018

Asakusa Framework 0.10.1 documentation [https://docs.asakusafw.com/0.10.1/release/ja/html/index.html]

新機能と主な変更点

ロギング演算子 を使用したアプリケーションが正しくコンパイルされないことがある不具合の修正

マルチプロジェクト構成で eclipse タスク実行時、Eclipseプロジェクトファイルが正しく作成されないことがある動作を改善

Asakusa CLI および Direct I/O CLI に日本語メッセージリソースを追加

対応プラットフォーム のアップデート ( Spark 2.3 , HDP 2.6.5 , Gradle 4.7 ) とこれに伴う修正

その他、細かな機能改善およびバグフィックスが含まれます。すべての変更点は Changelogs を参照してください。

互換性に関して

本リリースでは過去バージョンとの互換性に関する特別な情報はありません。

Release 0.10.0

Nov 29, 2017

Asakusa Framework 0.10.0 documentation [https://docs.asakusafw.com/0.10.0/release/ja/html/index.html]

はじめに

新機能と主な変更点

ビューAPI

Asakusa CLI

Direct I/O CLI (試験的機能)

Asakusa Vanilla

@Once, @Spill注釈

組み込みHadoopライブラリー

デプロイメント手順の変更

その他の変更点

非推奨化機能と削除された機能

Asakusa on MapReduceの非推奨化

実行エンジンについて

MapReduce関連機能について

今後の予定

互換性に関して

Asakusa Frameworkのデプロイメント手順の変更

Asakusa on M³BP のHadoop連携に関する設定の変更

Direct I/O Hive - Parquetファイルフォーマットの変更

バージョン 0.8系以前からのマイグレーションについて

はじめに

本バージョンでは ビューAPI などのAsakusa DSLに対するいくつかの拡張機能や、新しいコマンドラインインターフェース Asakusa CLI などの機能追加が行われました｡ またこれらの機能を実現するため、Operator DSLコンパイラを刷新するなどAsakusa Frameworkの内部にも大幅な変更と拡張が行われました。

これらの機能拡張を検討し、また今後のAsakusa Framework開発の計画を検討する過程で、 Hadoop MapReduceを実行基盤として利用する Asakusa on MapReduce については今後も継続して Asakusa on Spark や Asakusa on M3BP といった他の実行エンジンと同等の機能や品質を維持することは困難であると判断し、本バージョンから Asakusa on MapReduce を非推奨機能 として位置づけました。

このため、本バージョンで追加されたいくつかの機能拡張に、Asakusa on MapReduceは対応していません。

Asakusa on MapReduceの非推奨機化について詳しくは、本リリースノートの後半 Asakusa on MapReduceの非推奨化 にて説明しています。

新機能と主な変更点

ビューAPI

ビューAPI はAsakusa DSLの拡張機能で、データフロー上の任意の中間出力を、演算子から柔軟に参照するためのインターフェースを提供します。ビューは主にバッチ全体の定数表を効率よく扱うためのしくみで、以下のような定数データを外部データソースから取り込んで演算子メソッドから利用できます。

以下は「消費税率」などの税率テーブルをデータベースなどに保持し、演算子内から参照するサンプルコード片です。

private static final StringOption KEY_CTAX = new StringOption("消費税");

/**
 * 消費税を計算する。
 * @param detail 販売明細
 * @param taxTable 税率テーブル
 */
@Update
public void updateTax(
        SalesDetail detail,
        @Key(group = "name") GroupView<TaxEntry> taxTable) {

    // 税率テーブルから「消費税」に関する情報を取得する
    TaxEntry tax = taxTable.find(KEY_CTAX).get(0);

    // 総額から本体価格を算出する
    BigDecimal totalPrice = BigDecimal.valueOf(detail.getSellingPrice());
    BigDecimal priceWithoutTax = totalPrice.divide(BigDecimal.ONE.add(tax.getRate()));

    // ...
}

また、バッチ内で作成した中間データ（集計結果など）を上記と同様に定数表として参照したり、柔軟なテーブル化の機能を利用して複雑な条件を伴う結合処理（例えばデータ範囲を条件とする結合）などを、効率よく実現したりすることが可能です。

ビューAPIの具体的な利用方法については、以下のドキュメントを参照してください。

ビューAPI

Asakusa CLI

Asakusa CLI ( asakusa コマンド ) はバッチアプリケーションの開発支援機能、および運用機能を提供するコマンドラインインターフェースです。 Asakusa CLIは主に以下のような機能を提供します。

asakusa run - 簡易的なバッチアプリケーション実行ツール

asakusa run はバッチIDやバッチ引数を指定して、以下のようにバッチアプリケーションを実行します。

$ asakusa run m3bp.example.summarizeSales -A date=2011-04-01

Asakusa Frameworkは同様のバッチ実行ツールとして アプリケーションの実行 - YAESS を提供しています。 YAESSは様々な環境に対応するための数多くの設定や、実行状況を細粒度で示すため詳細なログ出力を行うといった特徴があります。これに対して、 asakusa run はシンプルで必要最低限のコマンドやオプション、ログ出力を提供するといった特徴があります。

このため、特にバッチアプリケーションの開発中やテスト時には asakusa run の利用が適することが多いでしょう。

asakusa list - DSL情報を様々な観点や粒度でリスト化して表示

asakusa list はコンパイル済みのバッチアプリケーションに対して、 batch , jobflow , operator といった各DSLのレイヤ、および directio , windgate , hive といった利用する外部連携コンポーネントといった観点でバッチアプリケーションが持つ構成情報をリストとして表示します。

以下は、バッチアプリケーションが利用するDirect I/Oの入出力定義の一覧を表示する例です。

$ asakusa list directio input m3bp.example.summarizeSales
master::item_info.csv
master::store_info.csv
sales::**/${date}.csv

$ asakusa list directio output m3bp.example.summarizeSales
result/category::result.csv
result/error::${date}.csv

asakusa generate - DSL情報からデータフロー構造やコンパイル後の実行計画などのグラフ情報を生成

asakusa generate の機能例として、グラフ表示ツール Graphviz [http://www.graphviz.org/] などと連携して以下のようなバッチアプリケーションのデータフロー構造を示すフローグラフを生成することができます。

従来、グラフ表示ツールと連携する同様の機能はAsakusa on MapReduceの機能として提供していました。 Asakusa CLIが提供するこの機能はAsakusa on MapReduce以外の実行エンジンで利用することができます。

Asakusa CLIの具体的な利用方法については、以下のドキュメントを参照してください。

Asakusa CLI ユーザーガイド

Direct I/O CLI (試験的機能)

Direct I/O CLI ( directio コマンド ) はDirect I/Oを利用する環境向けの運用ツールを提供するコマンドラインインターフェースです。 Direct I/O CLI は Asakusa CLIと類似のコマンド体系を持ち、Direct I/Oを利用する環境での運用で有用な以下の機能を提供します。

directio {list|mkdir|get|put|delete|copy|move} - Direct I/Oデータソース上のファイルの操作

directio configuration - Direct I/Oの設定情報を表示

directio transaction - Direct I/O トランザクションの操作

Direct I/O CLIの具体的な利用方法については、以下のドキュメントを参照してください。

Direct I/O CLI ユーザーガイド

Asakusa Vanilla

Asakusa Vanilla は、主にアプリケーションのテスト用に設計された、Asakusa Framework実行エンジンのリファレンス実装です。 Asakusa Vanillaは単一ノード上でアプリケーションを実行し、軽量で比較的コンパイル速度が速く、実行時にJVM以外の環境を必要としない、といった特徴を持っています。

Asakusa VanillaはAsakusa Framework バージョン 0.9.0 から試験的機能として提供していましたが、本バージョンより正式機能として アプリケーションのテスト - TestDriver で利用する標準の実行エンジンとして採用されました。本バージョンから、標準の設定でテストドライバの実行時にAsakusa Vanillaの上でバッチアプリケーションが実行されます。

なお、従来のバージョンではテストドライバの標準の実行エンジンはAsakusa on MapReduceをベースにした「スモールジョブ実行エンジン」を使用していました。本バージョンからAsakusa on MapReduceの非推奨化に伴い、スモールジョブ実行エンジンの利用も非推奨となりました。詳しくは Asakusa on MapReduceの非推奨化 にて後述します。

Asakusa Vanillaの詳細やテストドライバ以外での利用方法については、以下のドキュメントを参照してください。

Asakusa Vanilla

@Once, @Spill注釈

グループ結合演算子 や グループ整列演算子 では入力データを List として扱うため大きなグループを処理する場合にメモリが不足してしまう場合があり、このような巨大な入力グループへの対応のために従来のバージョンでは InputBuffer.ESCAPE を指定し、メモリ外のストレージを一時的に利用する機能を提供していました。

本バージョンから提供される @Once 注釈, @Spill 注釈は InputBuffer.ESCAPE より柔軟に巨大な入力グループへの対応を行うことができます。

@Once 注釈は 引数の型に Iterable<...> を使用し、各要素の内容は一度だけしか読み出せないという制約の元に、メモリ消費を抑え大きな入力グループを安全に取り扱うことができます。また、 @Once 注釈はメモリ上でのみ処理を行うため InputBuffer.ESCAPE 利用時のようなパフォーマンス低下などの問題は発生しません。

以下、 @Once 注釈の利用例です。

@CoGroup
public void cogroupWithOnce(
        @Key(group = "hogeCode") @Once Iterable<Hoge> hogeList,
        @Key(group = "hogeId") @Once Iterable<Foo> fooList,
        Result<Hoge> hogeResult,
        Result<Foo> fooResult
        ) {
    for (Hoge hoge : hogeList) {
        ...
    }
    for (Foo foo : fooList) {
        ...
    }
}

@Spill 注釈は従来の InputBuffer.ESCAPE のように、メモリ外のストレージを利用して大きな入力グループを扱うための指定方法です。 InputBuffer.ESCAPE と同様のデメリットが存在しますが、引数の型は List を利用することが可能で、 @Once 注釈では制約のある、リストに対する複数回アクセスやランダムアクセスが可能です。

また、従来の InputBuffer.ESCAPE は演算子の入力全体にかかる設定でしたが、 @Once 注釈, @Spill 注釈は 演算子の入力毎に指定することができます。

@Once 注釈, @Spill 注釈の詳細は、以下のドキュメントを参照してください。

演算子リファレンス - 巨大な入力グループへの対応

組み込みHadoopライブラリー

従来までのバージョンでは、各コンポーネントや実行エンジンで利用するHadoopの設定方法の一部が統一されておらず、各コンポーネントや実行エンジンごとに個別に異なる設定を行う必要がある、また場合によってはHadoop環境を複数用意する必要がある、などの問題が発生していました。

本バージョンでは、Asakusa Framework全体で利用可能な「組み込みHadoopライブラリー」を提供しています。これにより実行環境のHadoopと連携するための設定を統一し、また実行環境のHadoopと連携する必要がない場合には、以下のようにビルドスクリプトの設定で組み込みHadoopライブラリーを追加するだけでバッチアプリケーション全体を実行することが可能になりました。

build.gradle

asakusafwOrganizer {
    profiles.prod {
        hadoop.embed true
    }
}

一例として、WindGateを利用するには従来、実行環境のHadoopと連携する必要がない場合でもHadoop環境のセットアップや環境設定が必要でしたが、本バージョンでは組み込みHadoopライブラリーを利用することでも実行可能になりました。組み込みHadoopライブラリーを利用したWindGateの環境設定例は、 WindGateスタートガイド を参照してください。

またこの機能の追加に伴って、バージョン 0.9以前で Asakusa on M³BP を利用している場合、本バージョンへの移行時にHadoopとの連携に関するビルドスクリプトの設定変更が必要です。詳しくは、以下のドキュメントを参照してください。

Asakusa Gradle Plugin バージョン 0.10系 の変更点

その他詳細は、各コンポーネントや実行エンジンのドキュメントに記載のHadoop連携に関する説明を参照してください。

デプロイメント手順の変更

本バージョンでAsakusa CLIなどの機能が追加されたことに伴い、 Asakusa Frameworkのデプロイメントで使用するデプロイメントアーカイブの展開方法が変更になりました。

デプロイメントアーカイブの配置と展開後、以下のように java コマンド経由で $ASAKUSA_HOME/tools/bin/setup.jar を実行し、展開したファイルに対して適切な実行権限などを設定します。

mkdir -p "$ASAKUSA_HOME"
cd "$ASAKUSA_HOME"
tar -xzf /path/to/asakusafw-*.tar.gz
java -jar $ASAKUSA_HOME/tools/bin/setup.jar

バージョン 0.9以前では、この部分は find "$ASAKUSA_HOME" -name "*.sh" | xargs chmod u+x のようなコマンドを実行していましたが、本バージョンから展開後のファイル拡張子が一部変更されたため、この手順では正しくセットアップすることができません。

そのため、本バージョン以降は必ず上記のように $ASAKUSA_HOME/tools/bin/setup.jar を実行してセットアップを行ってください。

Asakusa Frameworkのデプロイメント手順については、以下のドキュメントを参照してください。

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

その他の変更点

テストドライバ に 一時的なフロー記述に対するテスト 機能を追加。テストケースに演算子テスト用のデータフローを記述してテストを実行することができます。

Asakusa Gradle Plguin に設定 asakusafw.sdk.yaess を追加。バッチアプリケーションに対するYAESSワークフロースクリプトの追加を設定可能（従来は常に追加）。

Direct I/O Hive Hive連携モジュールで使用する Hiveのバージョン を 1.1.1 から 1.2.2 にアップデート。

Direct I/O Hive 特定プラットフォームでParquetの DECIMAL 型を正しく扱うことができない問題を修正。詳しくは後述の Direct I/O Hive - Parquetファイルフォーマットの変更 を参照してください。

Asakusa on Spark Spark 2.0以降でYARN Clusterモードを使用するとバッチアプリケーションの成否にかかわらず常にエラーが返される問題の修正。

対応プラットフォーム 動作検証プラットフォームのアップデート。

その他、細かな機能改善およびバグフィックスが含まれます。すべての変更点は Changelogs を参照してください。

非推奨化機能と削除された機能

本バージョンで非推奨化になった機能と削除された機能を以下に示します。なおAsakusa on MapReduceについては Asakusa on MapReduceの非推奨化 にて後述します。

バージョン 0.9.0で非推奨となったビルドスクリプト設定の削除。詳しくは後述の バージョン 0.8系以前からのマイグレーションについて を参照してください。

Asakusa on M3BPの最適化設定 com.asakusafw.m3bp.buffer.access の設定変更 ( unsafe の使用 ) を非推奨化。

Asakusa Gradle Plugin:非推奨機能 testRunBatchapp タスクを非推奨化。

Asakusa on MapReduceの非推奨化

はじめに で述べた通り、Hadoop MapReduceを実行基盤として利用する Asakusa on MapReduce は本バージョンから非推奨機能となりました。

実行エンジンについて

本バージョン、およびバージョン 0.10系 ( 0.10.1 , 0.10.2 , … ) については、Asakusa on MapReduceについては他の実行エンジンへの移行期間として位置づけており、バージョン 0.9系 およびそれ以前に作成した Asakusa on MapReduce向けのバッチアプリケーションについては、本バージョンでも通常のマイグレーション手順を実施することで動作するようになっています。

ただし、本バージョンおよび今後のバージョンで追加される機能拡張については、基本的にAsakusa on MapReduceには対応しない方針となります。具体的には、本バージョンで追加になった以下の新機能はAsakusa on MapReduceでは利用できません。

ビューAPI

Asakusa CLI

@Once, @Spill注釈

本バージョン以降、バッチアプリケーションの実行エンジンについては Asakusa on Spark もしくは Asakusa on M3BP を利用することを推奨します。各実行エンジンの利用方法や互換性に関する注意点については、Asakusa on Spark および Asakusa on M3BP のドキュメントを参照してください。

MapReduce関連機能について

また、Asakusa on MapReduceに関連する機能やMapReduceをベースとするその他の機能も、本バージョンから非推奨機能となります。これらの機能には、スモールジョブ実行エンジンやAsakusa on MapReduce向けのDSL可視化、実行エンジンにMapReduceを利用したテスト機構などが含まれます。

本ドキュメントの Asakusa on MapReduce ページのドキュメントリンクに挙がっている機能はすべて非推奨機能となりますので、詳細はこのドキュメントページを確認してください。本バージョン以降、これらの機能の多くは動作検証が行われないため、今後これらの機能の一部は利用できなくなる可能性があります。

これらの機能のうち、重要なものについては本バージョンで代替機能が追加され、標準で利用可能になっています。詳しくは、バージョン 0.10.0 リリースノートの「新機能と主な変更点」を参照してください。

また、 Asakusa on Spark ではコンパイラ設定 spark.input.direct , spark.output.direct をそれぞれ false に指定することで、 MapReduce上でDirect I/Oの入出力を実行する機能が提供されていますが、本バージョンよりこの機能は非推奨機能となります。

今後の予定

Asakusa Framework バージョン 0.10系では、本バージョンと同様に上述の制約に基づいてAsakusa on MapReduceを利用することができます。 Asakusa on MapReduceを利用可能なバージョンを継続して提供するため、今後しばらくはバージョン 0.10系 のメンテナンスリリースを実施していく予定です。

将来リリース予定の Asakusa Framework バージョン 1.0 では、Asakusa on MapReduceおよびMapReduce関連機能は削除され、これらの機能は利用できなくなる予定です。

互換性に関して

ここでは過去バージョンからのマイグレーション時に確認すべき変更点について説明します。

標準のマイグレーション手順については以下のドキュメントで説明しています。

開発環境マイグレーションガイド

運用環境マイグレーションガイド

Asakusa Frameworkのデプロイメント手順の変更

本バージョンでAsakusa CLIなどの機能が追加されたことに伴い、Asakusa Frameworkのデプロイメント手順が一部変更になりました。詳細は本リリースノートの デプロイメント手順の変更 の項を参照してください。

Asakusa on M³BP のHadoop連携に関する設定の変更

過去バージョンの Asakusa on M³BP を利用している場合、本バージョンから Hadoopと連携するための設定方法が変更になりました。詳細は本リリースノートの 組み込みHadoopライブラリー の項を参照してください。

また本件の対応のために、ビルドスクリプト build.gradle の修正が必要になります。詳しくは Asakusa Gradle Plugin バージョン 0.10系 の変更点 を参照してください。

Direct I/O Hive - Parquetファイルフォーマットの変更

本バージョンでは Direct I/O Hive 利用時に特定プラットフォームでParquetの DECIMAL 型を正しく扱うことができない問題が修正されました。この変更に伴い、過去バージョンで作成したParquetファイルに対するデータフォーマットの互換性が失われました。過去バージョンのDirect I/O Hiveで作成したParquetファイルは、本バージョン以降のDirect I/O Hiveで正しく読み込むことが出来ない可能性があります。

過去バージョンで作成したParquetデータを本バージョン以降で読み込むためには、過去バージョンで作成したParquetファイルをいったん他のフォーマットに変更するなど、本バージョンのDirect I/Oで処理可能な形式に変換してデータの移行を行ってください。

バージョン 0.8系以前からのマイグレーションについて

本バージョンでは、バージョン 0.9.0で非推奨となった以下の古いビルドスクリプト設定が利用できなくなりました。

ディストリビューションプラグイン以外のAsakusa Gradle Plugin以外の定義。必ずディストリビューションプラグインを使用してください。

SDKアーティファクトを使用した依存性定義。Asakusa Frameworkが提供するアプリケーションライブラリの追加は、 asakusafw ブロック配下の sdk で指定してください。

これらの機能とビルドスクリプトの変更方法については、 Asakusa Gradle Plugin バージョン 0.9系 の変更点 に記載しています。バージョン 0.8系以前から本バージョンにマイグレーションを行う場合、必ずこのドキュメントの内容に従ってアプリケーションプロジェクトのビルドスクリプトを変更してください。また、アプリケーションプロジェクト全体のマイグレーション手順については、 Asakusa Gradle Plugin マイグレーションガイド を参照してください。

リンク

過去のリリースノート

Changelogs

過去のリリースノート

Asakusa Frameworkの過去バージョンのリリースノートです。

すべての変更点一覧は Changelogs も参照してください。

Release 0.9.2

Aug 07, 2017

Asakusa Framework 0.9.2 documentation [https://docs.asakusafw.com/0.9.2/release/ja/html/index.html]

新機能と主な変更点

DMDLプロパティ参照

DMDLプロパティ参照は、DMDLのレコードモデルおよび射影モデルに対して、複数のプロパティを単一のコレクションとして利用する機能をを提供します。

これらは固定長のリスト ( java.util.List ) またはマップ ( java.util.Map ) として利用でき、それぞれの要素はデータモデル内に存在するプロパティの参照を表します。 つまり、データモデル中のプロパティの値を変更するとリストやマップの値も変化し、リストやマップに対して変更を行うと、対応するプロパティの値が変化します。

このプロパティ参照を上手に利用すると、データモデル内に存在する「プロパティの繰り返し」を容易に処理できるようになります。

詳しくは、以下のドキュメントを参照してください。

DMDLユーザーガイド - プロパティ参照を定義する

WindGate JDBC ダイレクト・モード を正式機能としてリリース

バージョン 0.9.0 から試験的機能として公開していた WindGate JDBC ダイレクト・モード を正式機能として公開しました。

WindGate JDBC ダイレクト・モードとは、WindGateを利用したバッチアプリケーションの実行時にデータフロー処理を行うプロセスの内部で直接 WindGate JDBCによるデータベースへのインポート処理とエクスポート処理を行うように動作する、 Asakusa on M³BP 固有の最適化設定です。

WindGate JDBC ダイレクト・モードを利用することで、通常のWindGateよりもバッチアプリケーション全体の実行時間が大きく短縮できる可能性があります。

詳しくは、以下のドキュメントを参照してください。

Asakusa on M3BPの最適化設定 - WindGate JDBC ダイレクト・モード

WindGate - Oracleパーティションテーブルの並列読み出し

WindGateの最適化オプションに、Oracleパーティションテーブルに対する並列読み出しを行うオプションが追加されました。

この機能は、 WindGate JDBC ダイレクト・モード でのみ利用することができます。この機能の設定方法などは、 WindGate JDBC ダイレクト・モード のドキュメントを参照してください。

その他の変更点

Asakusa on Spark - Direct I/O のファイル出力処理中に処理が失敗しても正常終了として扱われることがある問題を修正

Asakusa on Spark - 単純集計演算子 の 集約関数 max を適用するデータに null が含まれていても、エラーにならず正常終了として扱われることがある問題を修正

Asakusa on Sparkの最適化設定 に Direct I/Oの入力スプリットを結合するオプション spark.hadoop.com.asakusafw.bridge.directio.input.combine を追加

Asakusa on M3BPの最適化設定 に 巨大な入力グループへの対応 で使用するディレクトリを変更するオプション com.asakusafw.dag.input.file.directory を追加

その他、細かな機能改善およびバグフィックスが含まれます。すべての変更点は Changelogs を参照してください。

互換性に関して

本リリースでは過去バージョンとの互換性に関する特別な情報はありません。

Release 0.9.1

Apr 26, 2017

Asakusa Framework 0.9.1 documentation [https://docs.asakusafw.com/0.9.1/release/ja/html/index.html]

新機能と主な変更点

Direct I/O formatted text

Direct I/Oでレコードやフィールドを区切り文字によって分割するデータ形式を取り扱うための機能 Direct I/O formatted text を追加しました。

従来、Direct I/Oで提供していた Direct I/O CSV や Direct I/O TSV などのテキストフォーマットを扱う機能と比べて、以下のような特徴を持っています。

多様なデータ形式を扱うきめ細かな設定が可能

データ形式に関する様々な設定をレコード全体、及びフィールド単位にそれぞれ設定することができます。

従来、事前にデータ整形処理が必要であったようなデータ形式の多くは、この機能で直接処理可能となります。

不整合データに対する柔軟な動作設定が可能

不整合データの検出時にエラーとして異常終了、警告を出力して処理を継続、単にスキップするなど様々な動作設定が可能です。

想定外のデータやアプリケーションの仕様変更などに対して柔軟な対応が可能となります。

詳しくは、以下のドキュメントを参照してください。

Direct I/O formatted text

Direct I/Oのデータフォーマットファイルをテストデータに指定

Direct I/Oを利用したアプリケーションのテストでは通常のテスト方法に加えて、Direct I/Oのデータフォーマットに対応するファイルをテストデータとして指定することが可能になりました。

例えば、CSVやTSVファイルを演算子やデータフローのテストに対する入力データや期待値データとして指定することができます。

詳しくは、以下のドキュメントを参照してください。

Direct I/O ユーザーガイド - データフォーマットに対応したファイルをテストデータに指定

その他の変更点

Direct I/O の 出力ファイル名のパターン で利用可能なプレースホルダで数値書式の対応を追加

結果型を利用する演算子のテスト 向けのユーティリティメソッド OperatorTestEnvironment#newResult を追加

Gradleラッパーのアップデート の手順で設定されるGradleラッパーの取得先URLをGradleの標準設定に合わせて http から https に変更

Asakusa on M3BP 標準の設定下で単一の入力グループが2GB以上になるとエラーが発生する制限事項を解消

Asakusa on M3BP 特定の条件でデータフローのコンパイルが正しく行われないことがある問題 1 を修正

WindGate JDBC ダイレクト・モード 特定の条件でデッドロックが発生する問題を修正

IntelliJ IDEAの利用 (試験的機能) ドキュメントの追加、及び従来の利用手順(Gradle IDEA Plugin拡張の利用)を非推奨化

対応プラットフォーム のアップデート

その他、細かな機能改善およびバグフィックスが含まれます。すべての変更点は Changelogs を参照してください。

1

https://github.com/asakusafw/asakusafw-compiler/pull/119

互換性に関して

本リリースでは過去バージョンとの互換性に関する特別な情報はありません。

Release 0.9.0

Dec 05, 2016

Asakusa Framework 0.9.0 documentation [https://docs.asakusafw.com/0.9.0/release/ja/html/index.html]

はじめに

今回のリリースよりAsakusa Frameworkのリリース方式を変更し、 Asakusa Frameworkのコアや拡張コンポーネント群をまとめた「ディストリビューション」形式でリリースを行います。

従来のリリース方式ではAsakusa Frameworkが提供する各コンポーネントは個別にリリースされていました。このためアプリケーション開発者は利用するコンポーネントのバージョンを個別に把握して設定する必要がありました。またこれにより、互換性がないコンポーネントバージョンを組み合わせて設定してしまう恐れがありました。

今回採用するディストリビューション形式のリリースにより、 Asakusa Frameworkが提供する様々なコンポーネントを単一のバージョンで利用可能にします。ディストリビューションに含まれる各コンポーネントの組み合わせは互換性があることが保証されます。

今回のリリース以降、このドキュメントはディストリビューションのリリース単位で作成されます。このドキュメントに記載するAsakusa Frameworkのバージョンは、特別な記載がない限りディストリビューションのバージョンを表します。

ディストリビューションに含まれる各コンポーネントとそのバージョンは Changelogs に記載しています。

新機能と主な変更点

Asakusa Framework Core/SDK

Asakusa Gradle Plugin - ディストリビューションプラグイン

「はじめに」で説明したディストリビューションを利用するために、 Asakusa Gradle Pluginに「ディストリビューションプラグイン」を追加しました。 Asakusa Framework 0.9.0 以降のプロジェクトテンプレートを利用する場合、標準でこのディストリビューションプラグインが使用されます。

バージョン 0.8系を利用しているプロジェクトからのマイグレーションについては、以下のドキュメントを参照してください。

Asakusa Gradle Plugin バージョン 0.9系 の変更点

WindGate - データベース接続時の最適化オプション

WindGateのデータベースとの接続時に利用する最適化オプションを設定する機能が追加されました。この機能は主にデータベース固有の最適化機能を利用するために使用することを想定しています。

Asakusa Framework 0.9.0 では Oracleのダイレクト・パス・インサートを利用するクエリーを発行するためのオプションが追加されています。

詳しくは、以下のドキュメントを参照してください。

WindGateユーザーガイド - データベース接続時の最適化オプション

Direct I/O - CSVフィールドのクォート方式の指定

Direct I/O CSVでフィールド値の内容に関わらず、常にクォート処理を行うモードが追加されました。また、CSVの各フィールドで個別にモードを指定するためのDMDL記述が追加されました。

Direct I/O CSVと連携するプロダクトでCSVフォーマットのクォートに関する制約がある場合に、この機能を利用することで連携時の問題を解消できる可能性があります。

詳しくは、以下のドキュメントを参照してください。

Direct I/O CSV - CSVフィールドの設定

Asakusa on Spark

Direct I/Oの出力処理をSpark上で実行

これまでのバージョンでは、Asakusa on Sparkを利用する場合でもDirect I/Oの出力処理はMapReduceジョブによって実行されていましたが、本バージョンより、Direct I/Oの出力処理はSpark上で実行されるようになりました。

この改善により、Asakusa on Spark上でDirect I/Oを利用するバッチアプリケーションについては、Hadoop MapReduceを実行するための環境設定は不要になりました。またMapReduceジョブの実行に必要なオーバーヘッドがなくなることで、バッチアプリケーションの実行性能が向上する可能性があります。

なお、この動作はコンパイラオプション spark.output.direct により変更可能です。詳しくは、以下のドキュメントを参照してください。

Asakusa on Spark リファレンス

またこの改善により、 Asakusa on Spark Iterative Extensions ではDirect I/Oの出力処理でも反復変数が利用可能になりました。

Spark 2.0に対応

本リリースより Spark 2.0 以降のバージョンに対応しました。

なお、本リリースより Spark 1.6 以前のバージョンは非対応になりました。

Asakusa on M³BP

WindGate JDBC ダイレクト・モード (試験的機能)

WindGate JDBC ダイレクト・モードとは、WindGateを利用したバッチアプリケーションの実行時にデータフロー処理を行うプロセスの内部で直接 WindGate JDBCによるデータベースへのインポート処理とエクスポート処理を行うように動作する、 Asakusa on M³BP 固有の最適化設定です。

WindGate JDBC ダイレクト・モードを利用することで、通常のWindGateよりもバッチアプリケーション全体の実行時間が大きく短縮できる可能性があります。

詳しくは、以下のドキュメントを参照してください。

Asakusa on M3BPの最適化設定 - WindGate JDBC ダイレクト・モード

その他

Asakusa Vanilla (試験的機能)

Asakusa Vanillaは、Asakusa Frameworkの内部機能として提供するDAG実行エンジン実装用のツールセットを使った、実行エンジンのリファレンス実装です。

Asakusa Vanillaは単一ノード上でアプリケーションを実行します。軽量で比較的コンパイル速度が速く、実行時にJVM以外の環境を必要としない、といった特徴を持っています。このため将来のバージョンでは、Asakusa Vanillaを エミュレーションモードによるアプリケーションテスト で利用する標準の実行エンジンに採用することを計画しています。

詳しくは、以下のドキュメントを参照してください。

Asakusa Vanilla

互換性に関して

対応プラットフォーム

本リリースでは、対応プラットフォームに関する重要な変更と非互換性があります。

Java (JDK)

Java7、およびJDK 7は非対応になりました。

Java7、およびJDK 7を利用している場合、Java 8 (JDK 8)に移行する必要があります。

Spark

Spark 1.6 以前のバージョンは非対応になりました。

Spark 1.6、およびそれ以前のバージョンを利用している場合、Spark 2.0 以降のバージョンに移行する必要があります。

変更内容の詳細やマイグレーション手順については、以下のドキュメント説明しています。

開発環境マイグレーションガイド

運用環境マイグレーションガイド

削除された機能

本リリースより、以下の機能は削除されました。

レガシーモジュール

Asakusa Legacy Gradle Plugin

YAESSログの可視化 ( summarizeYaessJob タスク )

Release 0.8.2

Dec 05, 2016

Asakusa Framework 0.8.2 documentation [https://docs.asakusafw.com/0.8.2/release/ja/html/index.html]

このバージョンはバグフィックスのみを含むメンテナンスリリースです。

変更点の詳細は Changelogs を参照してください。

Release 0.8.1

Jul 25, 2016

Asakusa Framework 0.8.1 documentation [https://docs.asakusafw.com/0.8.1/release/ja/html/index.html]

新機能と主な変更点

Direct I/O 出力カウンターの改善

Direct I/O の出力時に表示されるカウンターに、出力ポートごとの統計情報が表示されるようになりました。

com.asakusafw.directio.output.port.Statistics
  categorySummary.bytes=91
  categorySummary.files=1
  categorySummary.records=3
  errorRecord.bytes=432
  errorRecord.files=1
  errorRecord.records=3

Direct I/O line を正式機能としてリリース

バージョン 0.7.5 から試験的機能として公開していた Direct I/O line を正式機能として公開しました。

Direct I/O line は任意のテキストファイルを行ごとに読み書きするための機能です。 Direct I/Oが対応していないファイルフォーマットの入出力や、入力ファイルの整形や形式変換、バリデーションチェックなどの事前処理などに利用することができます。

Direct I/O lineの詳細は、以下のドキュメントを参照してください。

Direct I/O line

Asakusa Framework チュートリアル

Asakusa Frameworkのサンプルアプリケーションを作成しながら、フレームワークの基本的な使い方や開発の流れを紹介するチュートリアルを公開しました。

Asakusa Framework チュートリアル [https://docs.asakusafw.com/basic-tutorial/0.10/release/ja/html/index.html]

その他の変更点

その他、細かな機能改善およびバグフィックスが含まれます。すべての変更点は Changelogs を参照してください。

互換性に関して

非推奨機能

以下の機能の利用が非推奨になりました。

Asakusa Frameworkバージョンの指定 ( ビルドスクリプトの設定 )

バージョン 0.8.0 より、Asakusa FrameworkバージョンはAsakusa Gradle Pluginのバージョンから自動的に設定される値を利用することを推奨しています。

特にバージョン 0.7.6 以前に作成したプロジェクトから移行する場合は 開発環境マイグレーションガイド を確認して、必要に応じてビルドスクリプトを修正してください。

YAESSログの可視化

この機能はバージョン 0.6.2 から試験的機能として提供していましたが、MapReduce以外の実行プラットフォームでは適切な分析が行えないなどの問題があるため、本バージョンより非推奨となりました。

ライブラリの構成変更

Direct I/O lineが含まれるSDKアーティファクトが変更になりました。過去バージョンのDirect I/O lineを利用しているプロジェクトについては、開発環境マイグレーションガイド を確認してください。

将来のバージョンにおける非互換性を含む変更

将来のバージョンにおいて、以下のプロダクトバージョンを対応プラットフォームから除外することを計画しています。

Java: JDK7（JDK8にのみ対応）

Release 0.8.0

Apr 08, 2016

Asakusa Framework 0.8.0 documentation [https://docs.asakusafw.com/0.8.0/release/ja/html/index.html]

はじめに

Asakusa Frameworkは優れた開発生産性、高いパフォーマンスを発揮するバッチアプリケーションの開発、実行基盤として様々な改善を続けています。

今回のリリースでは、 新しい実行基盤である Asakusa on M³BP の新規公開、昨年からDeveloper Previewとして公開していた Asakusa on Spark の正式公開など重要なアップデートが多数含まれています。

また今回のリリースでは、より優れたプラットフォームへの対応を積極的に行うために、いくつかの古いプラットフォームの対応を削除しています。

新機能と主な変更点

Asakusa on M³BP

Asakusa on M³BP は、Asakusa DSLを始めとするAsakusa Frameworkの開発基盤を利用して作成したバッチアプリケーションに対して、 M³ for Batch Processing (https://github.com/fixstars/m3bp) を実行基盤として利用するための機能セットを提供します。

M³ for Batch Processing はDAG (Directed Acyclic Graph; 有向非循環グラフ) の形で表現されたタスクをマルチコア環境で効率よく処理するためのフレームワークで、以下のような特徴があります。

単一ノード上のマルチコア/マルチプロセッサ用に最適化

細粒度で動的なタスクスケジューリング

ほぼすべてオンメモリで処理

上記のような特徴のため、 小規模〜中規模のデータを扱うバッチに対して、Asakusa on M³BP によって単一ノード上で高速に処理できるようになりました。

Asakusa on M³BP の詳細は、以下のドキュメントを参照してください。

Asakusa on M3BP

Asakusa on Spark

2015年からDeveloper Previewとして公開していた Asakusa on Spark を正式機能として公開しました。

Asakusa on Sparkは、Asakusa DSLを始めとするAsakusa Frameworkの開発基盤を利用して作成したバッチアプリケーションに対して、Apache Spark (http://spark.apache.org) を実行基盤として利用するための機能セットを提供します。

特に中規模〜大規模のデータを扱うバッチに対して、Asakusa on Sparkは優れたパフォーマンスを発揮します。

Asakusa on Spark の詳細は、以下のドキュメントを参照してください。

Asakusa on Spark

Asakusa on Spark Iterative Extensions

Asakusa on Spark の拡張機能「Iterative Extensions」を試験的機能として公開しました。

Iterative Extensionsは、あるバッチに対してバッチ引数の一部または全部を変えながら同じバッチを連続して実行するための機能です。

Iterative Extensionsを適用したバッチを「反復バッチ」と呼びます。反復バッチは通常のバッチを連続して実行する場合と比べて、次の点で高速に実行できる可能性があります。

連続処理によるリソースの効率的な利用

連続するバッチアプリケーションを1つのSparkアプリケーションとして実行するため、特にYARN上での実行においては、アプリケーションコンテナの初期化などの分散オーバーヘッドが極小化される、コンテナリソースをシンプルな設定で最大限に利用できる、などの利点があります。

差分処理による最適化

反復バッチでは連続するバッチ間で再計算が不要な箇所は実行結果を再利用することがあるため、特に実行するバッチアプリケーション間での変更箇所が少ない場合には、バッチ間の差分処理による利点が大きくなります。

反復バッチは、日付範囲を指定した日次バッチの一括実行や、パラメータ・スイープによるシミュレーションといった用途に適しています。

Iterative Extensionsは、反復バッチを定義するためのAsakusa DSLの拡張構文、反復バッチを生成するするためのAsakusa DSLコンパイラの拡張、および反復バッチを実行するためのインターフェースや実行モジュールなどを提供します。

Asakusa on Spark Iterative Extensions の詳細は、以下のドキュメントを参照してください。

Asakusa on Spark Iterative Extensions

対応プラットフォームの更新

アプリケーションプロジェクトで使用するGradleの標準バージョンを2.12にアップデートしました。

その他、いくつかの動作検証プラットフォームを更新しています。詳しくは、 以下のドキュメントを参照してください。

対応プラットフォーム

また冒頭で述べた通り、今回のリリースではいくつかの古いプラットフォームの対応を削除しています。

詳しくは後述の互換性に関する説明を参照してください。

Asakusa Gradle Pluginの改善

Asakusa on M³BP や Asakusa on Spark のリリースに伴い、Gradle Plugin上で複数の実行基盤を統一的な方法で扱うための改善や、ビルド設定をシンプルに管理するための改善などをおこないました。

Asakusa Gradle Pluginの変更点については、以下のドキュメントを参照してください。

Asakusa Gradle Plugin バージョン 0.8系 の変更点

その他の変更点

その他、細かな機能改善およびバグフィックスが含まれます。

すべての変更点は Changelogs を参照してください。

互換性に関して

変更点

本リリースでは、対応プラットフォームに関する重要な変更と非互換性があります。

Warning

バージョン 0.8.0 は以前のバージョンからいくつかの重要な変更が行われました。過去のバージョンからのマイグレーションを検討する際には必ず以下の内容を確認してください。

Java (JDK)

Java6、およびJDK 6は非対応になりました。

Java6、およびJDK 6を利用している場合、Java 7(JDK 7)、またはJava 8 (JDK 8)に移行する必要があります。

Hadoop

Hadoop1系は非対応となりました。

開発環境にHadoop1系をインストールしている場合、Hadoop2系をインストールしてAsakusa FrameworkからはHadoop2系を利用するよう設定してください。

運用環境でHadoop1系を利用している場合、Hadoop2系に移行する必要があります。

Gradle

Gradleのバージョン1系は非対応になりました。

また、Asakusa Gradle Pluginにいくつか仕様変更が行われ、一部のタスクの動作やビルドスクリプトの設定方法が変更されています。

Maven

Mavenの利用は非対応になりました。

Mavenを利用しているアプリケーションプロジェクトは、Gradleを利用するよう移行する必要があります。

Asakusa Framework

Hadoop1系が非対応となったことにより、Asakusa Framwork バージョン 0.7.0 から導入された「Hadoopバージョン」が廃止になりました。

Asakusa Framework 0.7系では、Asakusa Framworkのバージョンは <version>-hadoop1, <version>-hadoop2 のように、利用するHadoopのバージョンを持つバージョン体系を導入していました。

本リリース以降は、Asakusa Frameworkのバージョンは単一のバージョン体系 ( 例えば本リリースのバージョンは 0.8.0 ) を使用します。

変更内容の詳細やマイグレーション手順については、以下のドキュメント説明しています。

開発環境マイグレーションガイド

運用環境マイグレーションガイド

Attention

過去のバージョンからのマイグレーション作業を行う場合、必ず 開発環境マイグレーションガイド と 運用環境マイグレーションガイド を確認してください。

Release 0.7.6

Dec 02, 2015

Asakusa Framework 0.7.6 documentation [https://docs.asakusafw.com/0.7.6/release/ja/html/index.html]

このバージョンはAsakusa DSLコンパイラの以下の問題に対応したメンテナンスリリースです。

MasterJoin系演算子のマスタ側入力に、 DataSize.TINY を含む2つ以上の入力を指定した場合に正しく動作しない問題を修正

その他、軽微なバグフィックスやドキュメント修正を含みます。

Release 0.7.5

Nov 19, 2015

Asakusa Framework 0.7.5 documentation [https://docs.asakusafw.com/0.7.5/release/ja/html/index.html]

新機能と主な変更点

Direct I/O line - 特定フォーマットに依存しないテキストファイルの入出力

Direct I/Oで任意のテキストファイルを行ごとに読み書きするための機能 Direct I/O line を追加しました。

Direct I/O lineはファイル内の行文字列とデータモデル内の1つの文字列型プロパティをマッピングする機能のみを提供します。行文字列の解析、生成などの処理はバッチアプリケーションの演算子として記述します。

Direct I/O lineは、以下のような用途に利用することを想定しています。

Direct I/Oが対応していないファイルフォーマットの入出力

例えば JSON [http://json.org] や LTSV [http://ltsv.org] といったフォーマットを扱う場合に、行文字列をパースする処理と組み合わせて利用します。

入力ファイルの整形や形式変換、バリデーションチェックなどの事前処理

例えばCSVファイルの一部にDirect I/Oでは直接扱えないような形式が含まれる場合に、事前に形式の変換を行うといった用途で利用します。

Direct I/O lineの詳細は、以下のドキュメントを参照してください。

Direct I/O line

GradleのDSLコンパイル時に対象のバッチアプリケーションを指定

Gradleから compileBatchapp タスクを指定してバッチアプリケーションのDSLコンパイルを実行する際に、 compileBatchapp --update <バッチクラス名> と指定することで、指定したバッチクラス名のみをバッチコンパイルすることができるようになりました。

詳細は、以下のドキュメントを参照してください。

Asakusa Gradle Plugin ユーザーガイド - バッチコンパイル対象のフィルタリング

開発環境向けの英語メッセージリソースの追加とAPIリファレンスの英語化

Asakusa DSLコンパイラのメッセージなど、従来日本語メッセージのみ提供していた機能に対して英語メッセージリソースを追加しました。

また、多くのAPIリファレンスの記述を日本語から英語に変更しました。

将来のバージョンで、全てのAPIリファレンスの記述を英語に統一する予定です。また、日本語によるAPIの説明は本ドキュメントに記述するよう統一する予定です。

サポートプラットフォームの更新

アプリケーション開発開発の動作検証プラットフォームにJava8(JDK 8)を追加しました。

また、アプリケーションプロジェクトで使用するGradleの標準バージョンを2.8にアップデートしました。

その他、いくつかの動作検証プラットフォームを更新しています。詳しくは、 以下のドキュメントを参照してください。

対応プラットフォーム

その他の変更点

その他、細かな機能改善およびバグフィックスが含まれます。すべての変更点は Changelogs を参照してください。

互換性に関して

将来のバージョンにおいて、以下のプロダクトバージョンを対応プラットフォームから除外することを計画しています。

Hadoop: Hadoop1系 (Hadoop2系にのみ対応)

Gradle: Gradleのバージョン1.12以前 (Gradle 2.X以降にのみ対応)

Java: JDK6 （JDK7以降にのみ対応)

See also

Hadoopバージョンについての詳細は Asakusa Framework デプロイメントガイド を参照してください

Release 0.7.4

Aug 11, 2015

Asakusa Framework 0.7.4 documentation [https://docs.asakusafw.com/0.7.4/release/ja/html/index.html]

新機能と主な変更点

YAESSコマンドオプションの追加

YAESSのバッチ実行用コマンドに以下のオプションを設定できるようになりました。

任意のプロファイルセット(構成ファイル)を指定 ( -D profile=<プロファイル名> )

実行時の環境変数を指定 ( -V key=value )

YAESSコマンドオプションの詳細は、以下のドキュメントを参照してください。

YAESSユーザーガイド

ParquetのDATE型に対応

Direct I/O HiveでParquetを利用する場合にHiveの DATE 型を利用できるようになりました。

なお、ParquetのDATE型をHiveから利用する場合、Hiveのバージョン 1.2 以上を利用する必要があります。

詳細は、以下のドキュメントを参照してください。

Direct I/O Hive

サポートプラットフォームの更新

いくつかのプラットフォームの対応バージョンを更新しています。

MapR 5.0.0

Hortonworks Data Platform 2.3

Apache Hive 1.2.1

また、いくつかのHadoopディストリビューションでJDK8上での動作検証を行いました。

なお、アプリケーションの開発環境でのJDK8の利用については、現時点では基本的な動作のみ検証しています。

詳しくは、 対応プラットフォーム を参照してください。

その他の変更点

Asakusa Gradle PluginがGradle 2.4以降で正常に動作しない問題を修正しました。

WindGate-SSHを異なるHadoopバージョン間の環境で利用した場合の動作を改善しました。

Windows上でHadoop2系を使ったエミュレーションモードが動作しない問題を修正しました。

その他、細かな機能改善およびバグフィックスが含まれます。すべての変更点は Changelogs を参照してください。

互換性に関して

将来のバージョンにおいて、以下のプロダクトバージョンを対応プラットフォームから除外することを計画しています。

Hadoop: Hadoop1系 (Hadoop2系にのみ対応)

Gradle: Gradleのバージョン1.12以前 (Gradle 2.X以降にのみ対応)

Java: JDK6 （JDK7以降にのみ対応)

See also

Hadoopバージョンについての詳細は Asakusa Framework デプロイメントガイド を参照してください

Release 0.7.3

Apr 22, 2015

Asakusa Framework 0.7.3 documentation [https://docs.asakusafw.com/0.7.3/release/ja/html/index.html]

新機能と主な変更点

Direct I/O 入力フィルター

Direct I/O を利用してファイルからデータを読み出す際に、ファイル単位やレコード単位で読み出すデータを制限する機能を追加。

入力フィルターを使うことで、従来のDirect I/Oの機能では記述しきれないような複雑な絞り込みを行えるようになります。バッチの実行パラメータと組み合わせることで、処理対象のデータを動的に制限することも可能です。また、フィルターによるデータの絞り込みをDSLコンパイラの最適化設定と組み合わせることで、アプリケーションの高速化が望めます。

Direct I/O 入力フィルターが提供する機能には以下のようなものがあります。

パスフィルターメソッド

入力の候補となるファイルパスに対して、個別に処理を行うかを決定するフィルタールールを記述します。

データフィルターメソッド

入力の候補となるデータモデルの内容に基づいて、個別に処理を行うかを決定するフィルタールールを記述します。

Direct I/O 入力フィルターについての詳細は、以下のドキュメントを参照してください。

Direct I/O ユーザーガイド - 入力データのフィルター

スモールジョブ実行エンジンの正式対応

Asakusa Framework バージョン 0.7.1 ( Release 0.7.1 ) で試験的機能として追加されたスモールジョブ実行エンジンに正式に対応しました。

正式対応に伴い、 エミュレーションモードによるアプリケーションテスト で利用するための設定方法が変更になっています。従来の設定で利用している環境も当面は引き続き利用可能ですが、できるだけ新しい設定方法を利用するようにしてください。

サポートプラットフォームの更新

いくつかのプラットフォームの対応バージョンを更新しています。

Apache Hadoop 2.6.0

Apache Hive 1.1.0

MapR 4.1.0

詳しくは、 対応プラットフォーム を参照してください。

その他の変更点

WindGate/JDBCでTRUNCATE時のクエリーをジョブフロー単位で指定可能になりました。

Direct I/O及びWindGateでCSVファイルの入力時にヘッダーの検証をスキップするオプションを追加しました。

テストドライバーを利用したインテグレーションテスト用のAPIを追加しました。

多相データフロー向けのコア演算子用APIを拡張しました。

ドキュメントの構成を改善しました。

その他、細かな機能改善およびバグフィックスが含まれます。すべての変更点は Changelogs を参照してください。

互換性に関して

Java SE Development Kit (JDK)

本バージョンからJDK6の利用は非推奨となりました。開発環境、運用環境共にJDK7を利用してください。

Asakusa Frameworkが動作検証を行なっているJavaのバージョンについては、 対応プラットフォーム を参照してください。また、開発環境で利用するJavaについての詳細は、 開発環境のJava を参照してください。

なお、将来のバージョンではJDK6の利用は非対応とすることを計画しています。

過去バージョンからのマイグレーション情報については、以下のドキュメントを参照してください。

開発環境マイグレーションガイド

運用環境マイグレーションガイド

Release 0.7.2

Jan 05, 2015

Asakusa Framework 0.7.2 documentation [https://docs.asakusafw.com/0.7.2/release/ja/html/index.html]

新機能と主な変更点

Windows上でのアプリケーション開発に対応

アプリケーション開発環境の対応プラットフォームとしてWindowsを追加しました。

Asakusa Framework スタートガイド for Windows ではWindows上にアプリケーション開発環境を構築し、サンプルアプリケーションを例に開発環境を利用する方法を紹介しています。

Windowsでは運用機能に制限がありますが、アプリケーションの開発、テスト、ビルド機能のほぼすべてを利用することができます。

Hive 0.14に対応

Direct I/O Hive がHive 0.14.0に対応しました。

Direct I/O Hiveが出力するParquetフォーマットで TIMESTAMP や DECIMAL 型などHive 0.14で新たに対応したデータタイプを利用することができるようになりました。

その他の変更点

その他、細かな機能改善およびバグフィックスが含まれます。すべての変更点は Changelogs を参照してください。

互換性に関して

本リリースでは過去バージョンとの互換性に関する特別な情報はありません。

過去バージョンからのマイグレーション情報については、以下のドキュメントを参照してください。

開発環境マイグレーションガイド

運用環境マイグレーションガイド

Release 0.7.1

Nov 20, 2014

Asakusa Framework 0.7.1 documentation [https://docs.asakusafw.com/0.7.1/release/ja/html/index.html]

新機能と主な変更点

小さなデータの処理性能を改善 (Experimental)

10MB程度の非常に小さなデータを処理するステージについて、実行性能を向上させる「スモールジョブ実行エンジン」を追加しました。

バッチアプリケーション内に小さなデータを処理するステージが多数含まれる場合、この機能を有効にすると性能が改善する場合があります。

また、常に小さなデータを利用する開発環境上のテスト実行では、この機能と エミュレーションモード を組み合わせて利用することで、テストの実行時間を大幅に短縮できます。

運用環境で本機能を有効にするには、以下を参照してください。

MapReduceタスクの最適化設定

開発環境で本機能を有効にするには、以下を参照してください。

エミュレーションモードによるアプリケーションテスト

サポートプラットフォームを追加

対応プラットフォームにHortonworks Data Platform 2.1を追加しました。

その他、いくつかのプラットフォームの対応バージョンを更新しています。

詳しくは、 対応プラットフォーム を参照してください。

その他の変更点

その他、細かな機能改善およびバグフィックスが含まれます。すべての変更点は Changelogs を参照してください。

互換性に関して

本リリースでは過去バージョンとの互換性に関する特別な情報はありません。

過去バージョンからのマイグレーション情報については、以下のドキュメントを参照してください。

開発環境マイグレーションガイド

運用環境マイグレーションガイド

Release 0.7.0

Sep 25, 2014

Asakusa Framework 0.7.0 documentation [https://docs.asakusafw.com/0.7.0/release/ja/html/index.html]

新機能と主な変更点

Direct I/O Hive

Apache Hive [https://hive.apache.org/] で利用されるいくつかのファイルフォーマットをDirect I/Oで直接取り扱えるようになりました。これにより、Apache Hiveのテーブルデータをアプリケーションから直接作成できるようになります。

本フィーチャーには主に以下の改善が含まれています。

Parquet / ORCFile フォーマット

さまざまなクエリーエンジンがサポートしている、ParquetとORCFileフォーマットをDirect I/Oから読み書きできるようになりました。

DMDL上での各種フォーマットのサポート

DMDLから各種Hive対応フォーマット向けのDataFormatクラスを自動生成できるようになりました。

また、上記の方法で作成したデータモデルから、Hive Metastore向けにDDLスクリプトを自動生成できるようになりました。

Direct I/O Hiveについて詳しくは、以下のドキュメントを参照してください。

Direct I/O Hive

Hadoop2系に正式対応

従来のHadoop1系に加え、以前のバージョンから試験的機能として対応していたHadoop2系に本バージョンから正式に対応しました。これにより、最新のHadoopディストリビューション上でAsakusa Frameworkのアプリケーションを安全に実行できます。

なお、正式にサポートするHadoopのバージョンラインが複数になったことにより、Asakusa Frameworkのバージョン体系もそれに合わせて変化しています。詳しくは以下のドキュメントを参照してください。

開発環境マイグレーションガイド - Asakusa Frameworkのバージョン体系の変更

本バージョンより、Gradleを利用したビルドシステムにおいて、開発環境や様々な運用環境で異なるHadoopのバージョンラインを使い分けられるようになりました。利用方法については以下のドキュメントを参照してください。

Asakusa Gradle Plugin ユーザーガイド

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

テストドライバーの改善

テストドライバーに以下の改善が加えられています。

Excelの数式をサポート

Excelによるテストデータ定義において、セルに数式を指定できるようになりました。これにより、より柔軟な方法でテストデータの定義を行えるようになります。

いくつかの比較形式を追加

Excelによるテストデータ定義において、誤差を許す比較や、大小比較をサポートしました。

本機能を利用する場合、新しいバージョンのテストデータテンプレートが必要になります。Excelのテストデータテンプレートを再生成してください。

テストデータの事前検証

テストデータやテスト条件に形式的な問題がある場合、Asakusa DSLのコンパイルやHadoop上での実行に先立ってエラーが報告されるようになりました。

Excelによるテストデータ定義に関して詳しくは、以下のドキュメントを参照してください。

Excelによるテストデータ定義

実行時パフォーマンスの改善

以下の機能により、全体的なパフォーマンス改善が加えられています。

ライブラリファイルのキャッシュ

フレームワークやアプリケーションのライブラリファイル群をHadoop上にキャッシュして再利用できるようになりました。

ステージ間の新しい中間データ形式

中間データに独自の形式を利用するようになりました。また、中間データの入出力をマルチコアプロセッサー向けに改善しました。

Mapタスクのスケジューリングを改善

Mapタスクの結合を行う遺伝的アルゴリズムを見直し、よりデータローカリティを重視するようになりました。

これらの機能に関する設定など詳しくは、以下のドキュメントを参照してください。

ライブラリキャッシュの設定

MapReduceタスクの最適化設定

その他、 対応プラットフォーム のアップデートや細かな機能改善およびバグフィックスが含まれます。

すべての変更点は Changelogs を参照してください。

互換性に関して

本リリースには、過去のリリースに対していくつかの潜在的な非互換性が存在します。

Java SE Development Kit (JDK)

アプリケーションプロジェクトの標準設定で利用するJavaのバージョンをJDK 6からJDK 7に変更しました。

Java 7に対応していないHadoopディストリビューション上でアプリケーションを実行する場合、手動でJDK 6に戻す必要があります。

Gradle

Gradle 2.1に対応しました。

以前のAsakusa FrameworkはGradle 2.0以降に対応していません。プロジェクトのAsakusa Frameworkのバージョンをダウングレードする場合に注意が必要です。

Maven

本バージョンより非推奨となりました。当面は引き続き利用可能ですが、できるだけGradleを利用するようにしてください。

マイグレーション手順については Asakusa Gradle Plugin ユーザーガイド - Mavenプロジェクトのマイグレーション を参照してください。

Framework Organizer Plugin (Gradle)

新機能の追加に伴い、いくつかのタスクが非推奨/利用不可能になりました。

詳しくは、 Asakusa Gradle Plugin:非推奨機能 を参照してください。

過去バージョンからのマイグレーション情報については、以下のドキュメントを参照してください。

開発環境マイグレーションガイド

運用環境マイグレーションガイド

Warning

バージョン 0.7.0 は以前のバージョンからいくつかの重要な変更が行われました。過去のバージョンからのマイグレーションを検討する際には必ず 開発環境マイグレーションガイド の内容を確認してください。

Release 0.6.2

May 22, 2014

Asakusa Framework 0.6.2 documentation [https://docs.asakusafw.com/0.6.2/release/ja/html/index.html]

新機能と主な変更点

「小さなジョブ」の実行に関する最適化オプションの追加

Asakusa Frameworkのアプリケーション実行時における最適化設定として、以下のオプションを追加しました。

Mapperごとにジョブの入力データサイズを判定し、データが小さい場合にMapperに対する入力スプリットを1つにまとめる: com.asakusafw.input.combine.tiny.limit

ジョブの入力データサイズを判定し、データが小さい場合に起動するReduceタスクを 1 に再設定する: com.asakusafw.reducer.tiny.limit

実行するアプリケーションの特性に応じてこれらのオプションを有効にすることで、計算リソースの無駄遣いを抑制したり、タスク起動のオーバーヘッドを削減したりすることでアプリケーション実行時のパフォーマンスが向上する可能性があります。

詳しくは、 Hadoopパラメータの設定 の上記設定項目の説明を参照してください。

対応プラットフォームのアップデート

動作検証プラットフォームのHadoopディストリビューションに CDH5 2 を追加しました。また、Amazon EMR 3 など一部のHadoopディストリビューションの動作検証バージョンをアップデートしました。

Hadoop2系での動作については、MRv2(YARN)上でアプリケーションを実行した際に不適切な最適化が適用されることによる性能上の問題や、MRv1上でアプリケーションが正常に実行されないことがある不具合などを修正し、安定性を向上させています。

アプリケーション開発環境については、Ubuntu Desktop 14.04 4 や Gradle 1.12 5 など動作検証プラットフォームのアップデートを行いました。

対応プラットフォームの一覧は、 対応プラットフォーム を参照してください。

Attention

本バージョンでは、Hadoop2系の対応は試験的機能として提供されます。 Hadoop2系の利用について詳しくは Hadoop2系の運用環境でAsakusa Frameworkを利用する を参照してください。

2

http://www.cloudera.co.jp/products-services/cdh/cdh.html

3

http://aws.amazon.com/jp/elasticmapreduce/

4

http://www.ubuntu.com/desktop

5

http://www.gradle.org/

YAESSログの可視化

試験的機能として、YAESSの実行時ログからCSV形式のレポートファイルを生成するYAESS Log Analyzerツール を追加しました。アプリケーションの実行時間の分析などに有用です。

詳しくは、 YAESSログの可視化 を参照してください。

互換性に関して

本リリースでは過去バージョンとの互換性に関する特別な情報はありません。

過去バージョンからのマイグレーション情報については、以下のドキュメントを参照してください。

開発環境マイグレーションガイド

運用環境マイグレーションガイド

Release 0.6.1

Mar 19, 2014

Asakusa Framework 0.6.1 documentation [https://docs.asakusafw.com/0.6.1/release/ja/html/index.html]

新機能と主な変更点

本リリースの新機能と主な変更点は以下の通りです。

以下の機能をSandboxから標準機能に昇格

テストドライバーのエミュレーションモード実行: エミュレーションモードによるアプリケーションテスト

バッチテストランナーAPI: テストドライバーユーザーガイド - インテグレーションテスト

Direct I/O の入力ファイルが存在しない場合にエラーとせず処理を続行するオプションを追加。

DirectFileInputDescription#isOptional() : Direct I/O ユーザーガイド

Asakusa Gradle Plugin が ThunderGate に対応、また内部動作と拡張性に関する多くの改善。

その他、細かな機能改善およびバグフィックスが含まれます。すべての変更点は Changelogs を参照してください。

互換性に関して

本リリースでは過去バージョンとの互換性に関する特別な情報はありません。

過去バージョンからのマイグレーション情報については、以下のドキュメントを参照してください。

開発環境マイグレーションガイド

運用環境マイグレーションガイド

Release 0.6.0

Feb 17, 2014

Asakusa Framework 0.6.0 documentation [https://docs.asakusafw.com/0.6.0/release/ja/html/index.html]

新機能と主な変更点

標準のビルドシステムをGradleに移行

Shafu - Gradleプロジェクト用Eclipse Plugin

テストドライバーにJavaオブジェクトによるテストデータ指定を追加

アプリケーションビルド時のログを改善

試験的機能(Sandbox)

アプリケーションテスト用のエミュレーションモード

入力データサイズに応じて自動的にローカルモードでジョブを実行

互換性に関して

新機能と主な変更点

標準のビルドシステムをGradleに移行

バッチアプリケーションの開発で使用する標準のビルドツールを従来のバージョンで使用していたMavenからGradleに移行しました。

バージョン 0.5.2 から試験的に提供していた Asakusa Gradle Plugin に対して多くの改善とバグフィックスを行い、これを標準機能に昇格しました。また、Asakusa Frameworkのドキュメント全体をGradleを利用した説明に変更しています。

Gradleを使ったアプリケーション開発の詳細や、Mavenを利用しているアプリケーションプロジェクトをGradleを利用したプロジェクトに移行する方法などについては以下のドキュメントを参照してください。

Asakusa Gradle Plugin ユーザーガイド

Mavenの利用について

本バージョン、およびAsakusa Framework 0.6 系ではMavenを使ったアプリケーションの開発もサポートしています。

Asakusa Framework 0.7 系以降の将来のバージョンで、Mavenによるアプリケーション開発を非推奨とすることを検討しています。

Shafu - Gradleプロジェクト用Eclipse Plugin

標準のビルドシステムをGradleに移行したことにあわせて、Gradleを利用するアプリケーションプロジェクトの開発をサポートするEclipseプラグイン「Shafu (車夫)」を公開しました。

Shafu - Asakusa Gradle Plug-in Helper for Eclipse - [https://docs.asakusafw.com/jinrikisha/ja/html/shafu.html]

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

テストドライバーにJavaオブジェクトによるテストデータ指定を追加

テストドライバーに指定可能なテストデータの形式を従来のExcelとJson形式に加え、Javaオブジェクトの指定が可能になりました。

詳しくは、 テストドライバーユーザーガイド の「入力データと期待データをJavaで記述する」を参照してください。

アプリケーションビルド時のログを改善

DMDLのコンパイルやAsakusa DSLのコンパイル、テストドライバーの実行時に出力されるログなどの出力内容を改善しました。

試験的機能(Sandbox)

アプリケーションテスト用のエミュレーションモード

試験的機能として、アプリケーションテスト用のエミュレーションモードを公開しました。

エミュレーションモードでAsakusa DSLのテストを実行すると、Asakusa Frameworkが提供するラッパー機構を利用してHadoopの処理を実行します。

通常のテスト実行とは異なり、テストを実行しているプロセス内でほとんどの処理が行われるため、デバッグモードのブレークポイントなどを利用できるようになります。また、カバレッジツールと連携して演算子メソッドのテストカバレッジを確認しやすくなります。

また、エミュレーションモードと連携したインテグレーションテスト用のツールとしてバッチテストランナーAPIを追加しました。

エミュレーションモードの詳細や利用方法などについては、以下のドキュメントを参照してください。

エミュレーションモードによるアプリケーションテスト

入力データサイズに応じて自動的にローカルモードでジョブを実行

試験的機能として、入力データサイズに応じて自動的にローカルモードでHadoopジョブを実行する実行時プラグインを公開しました。

このプラグインを利用することでバッチの実行にかかるHadoopのオーバーヘッドが適切に調整され、バッチ実行時間が改善する可能性があります。

現時点でこのプラグインは基本的な動作確認のみを行なっており、動作検証プラットフォームは Apache Hadoop 1.2.1 のみです。

利用方法は以下のREADMEを参照してください。

https://github.com/asakusafw/asakusafw-sandbox/blob/0.6.0/asakusa-runtime-ext/README.md

互換性に関して

本リリースでは過去バージョンとの互換性に関する特別な情報はありません。

過去バージョンからのマイグレーション情報については、以下のドキュメントを参照してください。

開発環境マイグレーションガイド

運用環境マイグレーションガイド

Release 0.5.3

Dec 24, 2013

Asakusa Framework 0.5.3 documentation [https://docs.asakusafw.com/0.5.3/release/ja/html/index.html]

本リリースはAsakusa Frameworkの開発版リリースです。主な変更内容は以下の通りです。

Apache Hadoop 2.2.0 に試験的に対応

Hadoop2系の利用については、 Hadoop2系の運用環境でAsakusa Frameworkを利用する を参照してください。

JDK 7に対応

開発環境におけるJDK 7の利用については、 application/develop-with-jdk7 を参照してください。

Hadoopディストリビューション、アプリケーション開発環境の動作検証プラットフォームをアップデート

対応プラットフォーム を参照してください。

DMDLコンパイラ, DSLコンパイラ, Direct I/O実行時のエラーメッセージを改善

TestDriverのExcel 2007形式によるテストデータ定義に試験的に対応

その他、多くの細かな機能改善、およびバグフィックス

Release 0.5.2

Nov 20, 2013

Asakusa Framework 0.5.2 documentation [https://docs.asakusafw.com/0.5.2/release/ja/html/index.html]

本リリースはAsakusa Frameworkの開発版リリースです。主な変更内容は以下の通りです。

試験的機能として、Gradleベースの新ビルドシステムを提供

詳しくは、 Asakusa Gradle Plugin ユーザーガイド を参照してください。

Direct I/O CSV, Direct I/O TSV(Sandbox) に入出力データの圧縮/解凍機能を追加

その他、多くの細かな機能改善、およびバグフィックス。

Release 0.5.1

Jul 26, 2013

Asakusa Framework 0.5.1 documentation [https://docs.asakusafw.com/0.5.1/release/ja/html/index.html]

本リリースはAsakusa Frameworkの開発版リリースです。主な変更内容は以下の通りです。

テストドライバーに演算子のトレースログを出力する機構を追加。

アプリケーション依存ライブラリの管理方法を改善。

DMDLコンパイラの日本語メッセージリソースを追加。

その他、多くの細かな機能改善、およびバグフィックス。

Release 0.5.0

May 9, 2013

Asakusa Framework 0.5.0 documentation [https://docs.asakusafw.com/0.5.0/release/ja/html/index.html]

本リリースはAsakusa Frameworkの開発版リリースです。主な変更内容は以下の通りです。

試験的にCDH4に対応 6 。またいくつかの動作検証プラットフォームの追加。

フレームワーク本体とバッチアプリケーションの構成情報を分離し、バッチアプリケーションの構成定義をシンプル化。

今後のAsakusa Frameworkの拡張のベースとなるFramework本体に対する多くのリファインメント。

その他、多くの細かな機能改善、およびバグフィックス。

6

CDH4上でAsakusa Frameworkを利用するためのドキュメントを、 Sandboxプロジェクトに公開しています。

Asakusa Framework Sandbox - CDH4上でAsakusa Frameworkを利用する [https://docs.asakusafw.com/sandbox/ja/html/administration/asakusa-on-cdh4.html]

Release 0.4.0

Aug 30, 2012

Asakusa Framework 0.4.0 documentation [https://docs.asakusafw.com/0.4.0/release/ja/html/index.html]

本リリースはAsakusa Frameworkの安定版リリースです。主な変更内容は以下の通りです。

[Direct I/O] ワイルドカード指定の出力機能などを追加し、試験的機能から正式機能として昇格。

[Asakusa DSL] コンパイラ最適化のチューニングおよびバグフィックス。

[YAESS] シミュレーションモードの実行やデプロイモジュールのバージョン検証機能などを追加。

動作検証プラットフォームの追加。

広範囲にわたるドキュメントの拡充と改善、および多くのドキュメントバグのフィックス。

その他、多くの細かな機能改善、およびバグフィックス。

Release 0.2.6

May 31, 2012

Asakusa Framework 0.2.6 documentation [https://docs.asakusafw.com/0.2/release/ja/html/index.html]

本リリースではYAESS マルチディスパッチ機能が追加されました。

これによりバッチやジョブフローなどを異なる複数のHadoopクラスターに振り分けて実行したり、それぞれ異なる設定で起動したりできるようになります。

ジョブ実行クラスターの振り分け

その他、多数の機能改善やバグフィックスが行われています。

Release 0.2.5

Jan 31, 2012

本リリースでは試験的な機能として「Direct I/O」が追加されました。これは、Hadoopクラスターから直接バッチの入出力データを読み書きするための機構です。

データの直接入出力 - Direct I/O

また、本バージョンでは対応プラットフォームの拡張として、従来のバージョンで対応していたHadoopディストリビューションであるCDH3に加えて、Apache Hadoop 0.20.203.0での動作検証が行われ、この環境で動作するための変更が行われています。

その他、細かな機能改善やバグフィックスが行われています。

Release 0.2.4

Dec 19, 2011

本リリースからWindGateがGA (Generally Available) となりました。 WindGateにはローカルのCSVに対するデータ入出力を行う機能が追加となっています。

また、本リリースではドキュメントの構成を見直し、内容を大幅に拡充しました。特に「Asakusa Framework入門」の追加、およびWindGateやYAESSに関する記述が多く追加されています。

Asakusa Framework 入門

旧バージョンを使っている開発環境を0.2.4に移行するにはマイグレーション作業が必要となります。詳しくは以下のマイグレーションガイドを参照してください。

開発環境マイグレーションガイド

その他、細かな機能改善やバグフィックスが行われています。

Release 0.2.3

Nov 16, 2011

本リリースでは、様々な環境に合わせて実行方法をカスタマイズすることが可能なバッチ実行ツール「YAESS」とThunderGateの差分インポート機能を実現する「ThunderGateキャッシュ」機能が追加されました。

アプリケーションの実行 - YAESS

Cache for ThunderGate

今回のリリースでは、旧バージョンを使っている開発環境を0.2.3に移行するためにマイグレーション作業が必要となります。詳しくは以下のマイグレーションガイドを参照してください。

開発環境マイグレーションガイド

その他、細かな機能改善やバグフィックスが行われています。

Release 0.2.2

Sep 29, 2011

本リリースではExperimental Featureとして「WindGate」が追加されました。

WindGateはThunderGateと同様にバッチに対するデータの外部入出力を行うモジュールですが、様々なプラットフォームに対応するよう設計され、ThunderGateに対してポータビリティが高いことが特徴です。

外部システムとの連携 - WindGate

その他、バグフィックスや細かい機能改善が行われています。

Release 0.2.1

Jul 27, 2011

Extract演算子の追加

Restructure演算子の追加

ThunderGateのCLOBサポート

その他バグフィックス

Release 0.2.0

Jun 29, 2011

DMDLの導入

テストドライバーの大幅な改善

その他多くのバグフィックス

Release 0.1.0

Mar 30, 2011

初版リリース

Changelogs

Release 0.10.3

Jun 12, 2019

Bundled Components

Component

Version

Milestone

Asakusa Framework Distribution

0.10.3 (↑)

[ asakusafw-distribution milestone:0.10.3 [https://github.com/asakusafw/asakusafw-distribution/issues?&q=milestone:0.10.3] ]

Asakusa Framework Core

0.10.3 (↑)

[ asakusafw milestone:0.10.3 [https://github.com/asakusafw/asakusafw/issues?&q=milestone:0.10.3] ]

Asakusa Framework Language Toolset

0.5.3 (↑)

[ asakusafw-compiler milestone:0.5.3 [https://github.com/asakusafw/asakusafw-compiler/issues?&q=milestone:0.5.3] ]

Asakusa on Spark

0.5.3 (↑)

[ asakusafw-spark milestone:0.5.3 [https://github.com/asakusafw/asakusafw-spark/issues?&q=milestone:0.5.3] ]

Asakusa on M³BP

0.3.3 (↑)

[ asakusafw-m3bp milestone:0.3.3 [https://github.com/asakusafw/asakusafw-m3bp/issues?&q=milestone:0.3.3] ]

M³ for Batch Processing

0.1.3

[ m3bp milestone:0.1.3 [https://github.com/fixstars/m3bp/issues?&q=milestone:0.1.3] ]

Asakusa on MapReduce

0.10.3 (↑)

[ asakusafw-mapreduce milestone:0.10.3 [https://github.com/asakusafw/asakusafw-mapreduce/issues?&q=milestone:0.10.3] ] (deprecated)

Release 0.10.2

Sep 26, 2018

Bundled Components

Component

Version

Milestone

Asakusa Framework Distribution

0.10.2 (↑)

[ asakusafw-distribution milestone:0.10.2 [https://github.com/asakusafw/asakusafw-distribution/issues?&q=milestone:0.10.2] ]

Asakusa Framework Core

0.10.2 (↑)

[ asakusafw milestone:0.10.2 [https://github.com/asakusafw/asakusafw/issues?&q=milestone:0.10.2] ]

Asakusa Framework Language Toolset

0.5.2 (↑)

[ asakusafw-compiler milestone:0.5.2 [https://github.com/asakusafw/asakusafw-compiler/issues?&q=milestone:0.5.2] ]

Asakusa on Spark

0.5.2 (↑)

[ asakusafw-spark milestone:0.5.2 [https://github.com/asakusafw/asakusafw-spark/issues?&q=milestone:0.5.2] ]

Asakusa on M³BP

0.3.2 (↑)

[ asakusafw-m3bp milestone:0.3.2 [https://github.com/asakusafw/asakusafw-m3bp/issues?&q=milestone:0.3.2] ]

M³ for Batch Processing

0.1.2

[ m3bp milestone:0.1.2 [https://github.com/fixstars/m3bp/issues?&q=milestone:0.1.2] ]

Asakusa on MapReduce

0.10.2 (↑)

[ asakusafw-mapreduce milestone:0.10.2 [https://github.com/asakusafw/asakusafw-mapreduce/issues?&q=milestone:0.10.2] ] (deprecated)

Release 0.10.1

Jun 27, 2018

Bundled Components

Component

Version

Milestone

Asakusa Framework Distribution

0.10.1 (↑)

[ asakusafw-distribution milestone:0.10.1 [https://github.com/asakusafw/asakusafw-distribution/issues?&q=milestone:0.10.1] ]

Asakusa Framework Core

0.10.1 (↑)

[ asakusafw milestone:0.10.1 [https://github.com/asakusafw/asakusafw/issues?&q=milestone:0.10.1] ]

Asakusa Framework Language Toolset

0.5.1 (↑)

[ asakusafw-compiler milestone:0.5.1 [https://github.com/asakusafw/asakusafw-compiler/issues?&q=milestone:0.5.1] ]

Asakusa on Spark

0.5.1 (↑)

[ asakusafw-spark milestone:0.5.1 [https://github.com/asakusafw/asakusafw-spark/issues?&q=milestone:0.5.1] ]

Asakusa on M³BP

0.3.1 (↑)

[ asakusafw-m3bp milestone:0.3.1 [https://github.com/asakusafw/asakusafw-m3bp/issues?&q=milestone:0.3.1] ]

M³ for Batch Processing

0.1.2

[ m3bp milestone:0.1.2 [https://github.com/fixstars/m3bp/issues?&q=milestone:0.1.2] ]

Asakusa on MapReduce

0.10.1 (↑)

[ asakusafw-mapreduce milestone:0.10.1 [https://github.com/asakusafw/asakusafw-mapreduce/issues?&q=milestone:0.10.1] ] (deprecated)

Release 0.10.0

Nov 29, 2017

Bundled Components

Component

Version

Milestone

Asakusa Framework Distribution

0.10.0 (↑)

[ asakusafw-distribution milestone:0.10.0 [https://github.com/asakusafw/asakusafw-distribution/issues?&q=milestone:0.10.0] ]

Asakusa Framework Core

0.10.0 (↑)

[ asakusafw milestone:0.10.0 [https://github.com/asakusafw/asakusafw/issues?&q=milestone:0.10.0] ]

Asakusa Framework Language Toolset

0.5.0 (↑)

[ asakusafw-compiler milestone:0.5.0 [https://github.com/asakusafw/asakusafw-compiler/issues?&q=milestone:0.5.0] ]

Asakusa on Spark

0.5.0 (↑)

[ asakusafw-spark milestone:0.5.0 [https://github.com/asakusafw/asakusafw-spark/issues?&q=milestone:0.5.0] ]

Asakusa on M³BP

0.3.0 (↑)

[ asakusafw-m3bp milestone:0.3.0 [https://github.com/asakusafw/asakusafw-m3bp/issues?&q=milestone:0.3.0] ]

M³ for Batch Processing

0.1.2

[ m3bp milestone:0.1.2 [https://github.com/fixstars/m3bp/issues?&q=milestone:0.1.2] ]

Asakusa on MapReduce

0.10.0 (↑)

[ asakusafw-mapreduce milestone:0.10.0 [https://github.com/asakusafw/asakusafw-mapreduce/issues?&q=milestone:0.10.0] ] (deprecated)

Release 0.9.2

Aug 07, 2017

Bundled Components

Component

Version

Milestone

Asakusa Framework Distribution

0.9.2 (↑)

[ asakusafw-distribution milestone:0.9.2 [https://github.com/asakusafw/asakusafw-distribution/issues?&q=milestone:0.9.2] ]

Asakusa Framework Core

0.9.2 (↑)

[ asakusafw milestone:0.9.2 [https://github.com/asakusafw/asakusafw/issues?&q=milestone:0.9.2] ]

Asakusa on MapReduce

0.9.2 (↑)

[ asakusafw milestone:0.9.2 [https://github.com/asakusafw/asakusafw/issues?&q=milestone:0.9.2] ]

Asakusa Framework Language Toolset

0.4.2 (↑)

[ asakusafw-compiler milestone:0.4.2 [https://github.com/asakusafw/asakusafw-compiler/issues?&q=milestone:0.4.2] ]

Asakusa on Spark

0.4.2 (↑)

[ asakusafw-spark milestone:0.4.2 [https://github.com/asakusafw/asakusafw-spark/issues?&q=milestone:0.4.2] ]

Asakusa on M³BP

0.2.2 (↑)

[ asakusafw-m3bp milestone:0.2.2 [https://github.com/asakusafw/asakusafw-m3bp/issues?&q=milestone:0.2.2] ]

M³ for Batch Processing

0.1.2

[ m3bp milestone:0.1.2 [https://github.com/fixstars/m3bp/issues?&q=milestone:0.1.2] ]

Release 0.9.1

Apr 26, 2017

Bundled Components

Component

Version

Milestone

Asakusa Framework Distribution

0.9.1 (↑)

[ asakusafw-distribution milestone:0.9.1 [https://github.com/asakusafw/asakusafw-distribution/issues?&q=milestone:0.9.1] ]

Asakusa Framework Documentation

0.9.1 (↑)

[ asakusafw-documentation milestone:0.9.1 [https://github.com/asakusafw/asakusafw-documentation/issues?&q=milestone:0.9.1] ]

Asakusa Framework Core

0.9.1 (↑)

[ asakusafw milestone:0.9.1 [https://github.com/asakusafw/asakusafw/issues?&q=milestone:0.9.1] ]

Asakusa Framework SDK

0.9.1 (↑)

[ asakusafw-sdk milestone:0.9.1 [https://github.com/asakusafw/asakusafw-sdk/issues?&q=milestone:0.9.1] ]

Asakusa on MapReduce

0.9.1 (↑)

[ asakusafw milestone:0.9.1 [https://github.com/asakusafw/asakusafw/issues?&q=milestone:0.9.1] ]

Asakusa Framework Language Toolset

0.4.1 (↑)

[ asakusafw-compiler milestone:0.4.1 [https://github.com/asakusafw/asakusafw-compiler/issues?&q=milestone:0.4.1] ]

Asakusa on Spark

0.4.1 (↑)

[ asakusafw-spark milestone:0.4.1 [https://github.com/asakusafw/asakusafw-spark/issues?&q=milestone:0.4.1] ]

Asakusa on M³BP

0.2.1 (↑)

[ asakusafw-m3bp milestone:0.2.1 [https://github.com/asakusafw/asakusafw-m3bp/issues?&q=milestone:0.2.1] ]

M³ for Batch Processing

0.1.2

[ m3bp milestone:0.1.2 [https://github.com/fixstars/m3bp/issues?&q=milestone:0.1.2] ]

Release 0.9.0

Dec 05, 2016

Bundled Components

Component

Version

Milestone

Asakusa Framework Distribution

0.9.0 (NEW)

[ asakusafw-distribution milestone:0.9.0 [https://github.com/asakusafw/asakusafw-distribution/issues?&q=milestone:0.9.0] ]

Asakusa Framework Documentation

0.9.0 (NEW)

[ asakusafw-documentation milestone:0.9.0 [https://github.com/asakusafw/asakusafw-documentation/issues?&q=milestone:0.9.0] ]

Asakusa Framework Core

0.9.0 (↑)

[ asakusafw milestone:0.9.0 [https://github.com/asakusafw/asakusafw/issues?&q=milestone:0.9.0] ]

Asakusa Framework SDK

0.9.0 (↑)

[ asakusafw-sdk milestone:0.9.0 [https://github.com/asakusafw/asakusafw-sdk/issues?&q=milestone:0.9.0] ]

Asakusa on MapReduce

0.9.0 (↑)

[ asakusafw milestone:0.9.0 [https://github.com/asakusafw/asakusafw/issues?&q=milestone:0.9.0] ]

Asakusa Framework Language Toolset

0.4.0 (↑)

[ asakusafw-compiler milestone:0.4.0 [https://github.com/asakusafw/asakusafw-compiler/issues?&q=milestone:0.4.0] ]

Asakusa on Spark

0.4.0 (↑)

[ asakusafw-spark milestone:0.4.0 [https://github.com/asakusafw/asakusafw-spark/issues?&q=milestone:0.4.0] ]

Asakusa on M³BP

0.2.0 (↑)

[ asakusafw-m3bp milestone:0.2.0 [https://github.com/asakusafw/asakusafw-m3bp/issues?&q=milestone:0.2.0] ]

M³ for Batch Processing

0.1.2

[ m3bp milestone:0.1.2 [https://github.com/fixstars/m3bp/issues?&q=milestone:0.1.2] ]

Release 0.8.2

Dec 05, 2016

[ asakusafw milestone:0.8.2 [https://github.com/asakusafw/asakusafw/issues?&q=milestone:0.8.2] ]

[ asakusafw-sdk milestone:0.8.2 [https://github.com/asakusafw/asakusafw-sdk/issues?&q=milestone:0.8.2] ]

Bundled Components

Component

Version

Asakusa Framework Core

0.8.2 (↑)

Asakusa on MapReduce

0.8.2 (↑)

Release 0.8.1

Jul 25, 2016

[ asakusafw milestone:0.8.1 [https://github.com/asakusafw/asakusafw/issues?&q=milestone:0.8.1] ]

[ asakusafw-sdk milestone:0.8.1 [https://github.com/asakusafw/asakusafw-sdk/issues?&q=milestone:0.8.1] ]

Bundled Components

Component

Version

Asakusa Framework Core

0.8.1 (↑)

Asakusa on MapReduce

0.8.1 (↑)

Release 0.8.0

Apr 08, 2016

[ asakusafw milestone:0.8.0 [https://github.com/asakusafw/asakusafw/issues?&q=milestone:0.8.0] ]

[ asakusafw-sdk milestone:0.8.0 [https://github.com/asakusafw/asakusafw-sdk/issues?&q=milestone:0.8.0] ]

Bundled Components

Component

Version

Asakusa Framework Core

0.8.0

Asakusa on MapReduce

0.8.0

Release 0.7.6

Dec 02, 2015

[ asakusafw milestone:0.7.6 [https://github.com/asakusafw/asakusafw/issues?&q=milestone:0.7.6] ]

[ asakusafw-sdk milestone:0.7.6 [https://github.com/asakusafw/asakusafw-sdk/issues?&q=milestone:0.7.6] ]

Release 0.7.5

Nov 19, 2015

[ asakusafw milestone:0.7.5 [https://github.com/asakusafw/asakusafw/issues?&q=milestone:0.7.5] ]

[ asakusafw-sdk milestone:0.7.5 [https://github.com/asakusafw/asakusafw-sdk/issues?&q=milestone:0.7.5] ]

Release 0.7.4

Aug 11, 2015

[ asakusafw milestone:0.7.4 [https://github.com/asakusafw/asakusafw/issues?&q=milestone:0.7.4] ]

[ asakusafw-sdk milestone:0.7.4 [https://github.com/asakusafw/asakusafw-sdk/issues?&q=milestone:0.7.4] ]

Release 0.7.3

Apr 22, 2015

[ asakusafw milestone:0.7.3 [https://github.com/asakusafw/asakusafw/issues?&q=milestone:0.7.3] ]

[ asakusafw-sdk milestone:0.7.3 [https://github.com/asakusafw/asakusafw-sdk/issues?&q=milestone:0.7.3] ]

Release 0.7.2

Jan 05, 2015

[ asakusafw milestone:0.7.2 [https://github.com/asakusafw/asakusafw/issues?&q=milestone:0.7.2] ]

[ asakusafw-sdk milestone:0.7.2 [https://github.com/asakusafw/asakusafw-sdk/issues?&q=milestone:0.7.2] ]

Release 0.7.1

Nov 20, 2014

[ asakusafw milestone:0.7.1 [https://github.com/asakusafw/asakusafw/issues?&q=milestone:0.7.1] ]

[ asakusafw-sdk milestone:0.7.1 [https://github.com/asakusafw/asakusafw-sdk/issues?&q=milestone:0.7.1] ]

Release 0.7.0

Sep 25, 2014

[ asakusafw milestone:0.7.0 [https://github.com/asakusafw/asakusafw/issues?&q=milestone:0.7.0] ]

[ asakusafw-sdk milestone:0.7.0 [https://github.com/asakusafw/asakusafw-sdk/issues?&q=milestone:0.7.0] ]

Release 0.6.2

May 22, 2014

[ asakusafw milestone:0.6.2 [https://github.com/asakusafw/asakusafw/issues?&q=milestone:0.6.2] ]

Release 0.6.1

Mar 19, 2014

[ asakusafw milestone:0.6.1 [https://github.com/asakusafw/asakusafw/issues?&q=milestone:0.6.1] ]

Release 0.6.0

Feb 17, 2014

[ asakusafw milestone:0.6.0 [https://github.com/asakusafw/asakusafw/issues?&q=milestone:0.6.0] ]

Release 0.5.3

Dec 24, 2013

[ asakusafw milestone:0.5.3 [https://github.com/asakusafw/asakusafw/issues?&q=milestone:0.5.3] ]

Release 0.5.2

Nov 20, 2013

[ asakusafw milestone:0.5.2 [https://github.com/asakusafw/asakusafw/issues?&q=milestone:0.5.2] ]

Release 0.5.1

Jul 26, 2013

[ asakusafw milestone:0.5.1 [https://github.com/asakusafw/asakusafw/issues?&q=milestone:0.5.1] ]

Release 0.5.0

May 9, 2013

[ asakusafw milestone:0.5.0 [https://github.com/asakusafw/asakusafw/issues?&q=milestone:0.5.0] ]

Release 0.4.0

Aug 30, 2012

[ asakusafw milestone:0.4.0 [https://github.com/asakusafw/asakusafw/issues?&q=milestone:0.4.0] ]

Release 0.2.6

May 31, 2012

[ asakusafw milestone:0.2.6 [https://github.com/asakusafw/asakusafw/issues?&q=milestone:0.2.6] ]

Release 0.2.5

Jan 31, 2012

[ asakusafw milestone:0.2.5 [https://github.com/asakusafw/asakusafw/issues?&q=milestone:0.2.5] ]

Release 0.2.4

Dec 19, 2011

[ asakusafw milestone:0.2.4 [https://github.com/asakusafw/asakusafw/issues?&q=milestone:0.2.4] ]

Release 0.2.3

Nov 16, 2011

[ asakusafw milestone:0.2.3 [https://github.com/asakusafw/asakusafw/issues?&q=milestone:0.2.3] ]

Release 0.2.2

Sep 29, 2011

[ asakusafw milestone:0.2.2 [https://github.com/asakusafw/asakusafw/issues?&q=milestone:0.2.2] ]

Release 0.2.1

Jul 27, 2011

[ asakusafw milestone:0.2.1 [https://github.com/asakusafw/asakusafw/issues?&q=milestone:0.2.1] ]

Release 0.2.0

Jun 29, 2011

[ asakusafw milestone:0.2.0 [https://github.com/asakusafw/asakusafw/issues?&q=milestone:0.2.0] ]

Release 0.1.0

Mar 30, 2011

The first release of Asakusa Framework.

プロダクトに貢献するには（バグ報告、パッチ投稿、メーリングリスト）

Asakusa Framework プロジェクトでは、みなさまの貢献をお待ちしています。

バグ報告をGitHub Issuesに登録してください [https://github.com/asakusafw/asakusafw-issues/issues]

各レポジトリへパッチを Pull Request として投稿してください

そのPull Requestがどういうものか、背景と問題、対処について説明をしてください

Javaコードの場合は、必ずIDEによる整形を行ってください

必ずユニットテストを書き、 CI [https://ci.asakusafw.com/] によるテストをパスしていることを確認してください

開発者がレビューの後マージします

ドキュメントを Pull Request として投稿してください

レビューの後マージします

ドキュメントへの反映は、しばらく時間が必要です

ドキュメントやソースコードによる貢献は、すべて Apache 2.0 ライセンスのもと利用されます（TODO: CLAを用意する）

ドキュメントおよびソースコードには、特許および商標権により保護された知的財産が含まれないことを確認してください

ニーズや事例、検証の結果、フィードバックを メーリングリストへ投稿してください [https://groups.google.com/a/asakusafw.com/forum/#!forum/users]

Asakusa Framework 入門

ここでは、Asakusa Frameworkの概要や導入方法について紹介しています。

Asakusa Framework全体の外観については Asakusa Framework概観 を、Asakusa Frameworkを初めて導入する場合には Asakusa Framework スタートガイド をそれぞれ参照してください。

Asakusa Framework概観

Asakusa Framework スタートガイド

開発の流れ

Asakusa Framework概観

Asakusa Frameworkのコンセプト

Asakusa Frameworkは、バッチアプリケーションを開発するための包括的なフレームワークです。複雑なデータフローやデータ構造、高い実行性能が要求される適用領域に対して、開発効率や信頼性、実行効率の優れたバッチアプリケーションを開発することを目的としています。

Asakusa Frameworkでは、JavaをベースにしたDSL(Domain Specific Language)を使ってバッチアプリケーションを記述します。このDSLはバッチアプリケーションを効率的に記述するための様々なインターフェースやテンプレートを提供し、規模や複雑性の増加に対して適切な粒度でコンポーネントを管理するソフトウェア構造を導入します。これによりシンプルで再利用性が高く、テストが記述しやすいバッチアプリケーションを開発することが可能です。

Asakusa Frameworkは、Hadoop 1 やSpark 2 , M³ for Batch Processing 3 といった様々な並列分散処理系のプラットフォームをバッチ処理基盤として利用することができます。これにより、バッチアプリケーションの特性やワークロードなどに応じて柔軟にプラットフォーム構成を選択することができます。各処理系に対応したDSLコンパイラは、バッチ処理を記述したDSLに対して様々な最適化を行い、高いパフォーマンスを発揮するバッチアプリケーションを生成します。

またDSLとそのコンパイラは、バッチ処理に付随する外部システムとのデータ連携やワークフローに関する動作を管理し、一貫性の高い安定したバッチ運用環境を提供します。その他の特徴として、Asakusa Frameworkはバージョン間、プラットフォーム間の互換性や相互運用性を重視しており、テクノロジーの進化やワークロードの変更といった環境の変化に対して、より優れたプラットフォームへの移行を容易にします。

Asakusa Frameworkは長いライフサイクルをもつバッチアプリケーションに対して、プラットフォームの改善を促進しつつ、優れた開発生産性、運用性を導入することで、堅牢で持続力のあるバッチ処理基盤を構築することを支援します。

1

http://hadoop.apache.org/

2

http://spark.apache.org/

3

https://github.com/fixstars/m3bp

Asakusa Frameworkの構成

Asakusa Frameworkは、 Asakusa DSL を中心としたフレームワークです。 Asakusa DSLはデータフロー形式のバッチ処理を記述することに特化した言語で、次のような特徴があります。

データフロー内のそれぞれの処理をJavaプログラムとして記述できる

データフローをデータフロー図と似た形式でそのまま記述できる

上記のような特徴を持つAsakusa DSLや、その他バッチ処理内で利用するデータモデルを定義するためのDSLを作成し、それぞれのDSLを処理するコンパイラに渡します。このコンパイラは、DSLの内容を解析して、以下のような情報を出力します。

ワークフロー定義

作成したバッチアプリケーション全体の処理の流れを表す情報です。ワークフローエンジンにこの情報を渡すことで、Asakusa Frameworkが生成する複雑なバッチの構造もワークフローエンジンで処理できるようになります。詳しくは バッチ実行ツール などを参照してください。

外部システム連携情報

バッチ処理内で利用するデータや、バッチ処理の結果データを外部システムとやり取りするための情報です。 Asakusa Frameworkでは外部システムとシームレスに連携して、バッチ処理を作成するための仕組みが用意されています。詳しくは 外部システム連携 などを参照してください。

データフロー処理を行うプログラム

入力されたデータをHadoopやSparkなどの各処理系で処理するためのプログラムです。 Asakusa DSLで記述されたデータフロー構造のプログラムは、コンパイラによって各処理系のプログラム群に変換されます。詳しくは Asakusa DSL などを参照してください。

データモデルプログラム

外部システム連携やデータフロー処理を行うプログラム内で利用されるデータモデルを表すプログラムです。 Hadoopや外部システム内では別々の方式で処理が行われますが、それらをつなぐのがこのデータモデルです。詳しくは データモデル定義DSL などを参照してください。

以下は、上記の内容を俯瞰する図です。

また、実行時にはそれぞれのコンポーネントに対し、DSLから生成されたそれぞれの情報を渡します。それぞれのコンポーネントは、これらの情報を元にバッチアプリケーションを分散システム上で協調しながら処理を進めていきます。

Asakusa Frameworkのコンポーネント

Asakusa Frameworkは主に以下のようなコンポーネントの組み合わせで成り立っています。

Asakusa DSL

データモデル定義DSL

自動テストサポート

外部システム連携

バッチ実行ツール

Asakusa DSL

Asakusa DSLは基幹向けのバッチ処理アプリケーションを作成するために開発されたDSLで、Asakusa Frameworkの中心を担っています。それぞれのバッチアプリケーションは、Asakusa DSLが提供する「語彙」を拡張したり組み合わせたりしてプログラムを記述し、最後に記述したプログラムをコンパイラに渡して、実行に必要なさまざまな情報を生成します。

Asakusa DSLについての詳しい情報は、 アプリケーションの実装 - Asakusa DSL を参照してください。

データモデル定義DSL

データモデル定義DSL (Data Model Definition Language: DMDL)はAsakusa DSL内で利用するデータモデルプログラムを作成するための言語です。データモデルが持つ構造を単純な方法で記述でき、そこから以下のような情報を生成します。

Hadoopの直列化形式

Javaの標準的なメソッド

外部システム連携 で利用するデータ変換ロジック

自動テストサポート で利用するテンプレート

データモデル定義DSLについての詳しい情報は、 アプリケーションの実装 - Asakusa Data Model を参照してください。

外部システム連携

外部システム連携は基幹システムでのバッチアプリケーションの肝ともなる部分で、Asakusa Frameworkでは以下のツールや機能を提供しています。

Direct I/O

Asakusa Frameworkの外でHadoopやその周辺に取り込んだデータを直接読み書きする機能。

詳しくは データの直接入出力 - Direct I/O を参照してください。

WindGate

ローカルファイルシステム上のフラットファイルや、JDBC経由でのデータベースアクセスなど、単純なデータソースとの連携を前提としたツール。

詳しくは 外部システムとの連携 - WindGate を参照してください。

なお、これらのツールとの連携はAsakusa DSLから記述できます。

自動テストサポート

Asakusa Frameworkには、Asakusa DSLで記述したアプリケーションの自動テストツールが含まれています。

バッチアプリケーションでは、通常、外部システム連携と複雑な業務ロジックを組み合わせて一連の処理を行います。そのようなアプリケーションに対し、この自動テストツールは以下のような処理を行います。

バッチアプリケーションをビルドする

定義されたテストデータを外部システムに流し込む

バッチアプリケーション全体を実行する

外部システムから結果データを取り出す

結果データを検証してレポートする

さらに、このテストツールは統合開発環境(IDE)やビルドツール内からも利用できます。そのため、開発の早い時期から積極的にテストを行え、また自動ビルドの環境も無理なく用意できるようになっています。

自動テストサポートについての詳しい情報は、 アプリケーションのテスト - TestDriver を参照してください。

バッチ実行ツール

Asakusa Frameworkが生成する情報は、外部システム連携やデータフローを処理を行うプログラムなど様々なもので、さらにそれらはジョブネットの構造を持っています。そのようなバッチを統一された方法で実行する手段として、以下のツールを提供しています。

Asakusa CLI

Asakusa CLI ( asakusa コマンド ) はバッチアプリケーションの開発支援ツール、および運用ツールを提供するコマンドラインインターフェースです。このサブコマンド asakusa run は、簡易的なバッチアプリケーション実行ツールを提供します。

詳しくは、 コマンドラインインターフェース - Asakusa CLI を参照してください。

YAESS

YAESSはAsakusa Frameworkで開発したバッチを実行するためのツールです。このツールは、バッチを実行する様々な環境にあわせて、自由に実行方法をカスタマイズできるように作成されています。

詳しくは、 アプリケーションの実行 - YAESS を参照してください。

Asakusa Framework スタートガイド

この文書では、Asakusa Frameworkをはじめて利用するユーザー向けに、Asakusa Frameworkを使ったバッチアプリケーションの開発、実行方法を簡単に説明します。

See also

本書より詳しい入門向けドキュメントとして、 Asakusa Framework チュートリアル [https://docs.asakusafw.com/basic-tutorial/0.10/release/ja/html/index.html] ではサンプルアプリケーションを作成しながらフレームワークの基本的な使い方や開発の流れを説明しています。

開発環境の準備

前提環境

Asakusa Frameworkを開発環境で利用するためには、開発環境に以下がセットアップされている必要があります。

ソフトウェア

バージョン

備考

JDK

JDK 8

JREは利用不可

Eclipse

4.4.2 以上を推奨

Shafuを利用する場合に使用

Attention

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

環境変数の設定

Asakusa Frameworkを開発環境で利用するには、以下の環境変数が必要です。

変数名

値

ASAKUSA_HOME

Asakusa Frameworkのインストールディレクトリを指定

JAVA_HOME

JDKのインストールディレクトリを指定

PATH

JDKのコマンドパスを追加: ${JAVA_HOME}/bin

Asakusa Frameworkの開発支援ツール

Asakusa Frameworkを使ったバッチアプリケーションの開発は、基本的にJavaを利用したアプリケーションの開発になりますが、いくつかの点でAsakusa Framework固有の環境設定やビルドに関する知識が必要になります。

そのため、Asakusa Frameworkではアプリケーションの開発をサポートするいくつかのツールを提供しています。

Shafu

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

Shafu - Asakusa Gradle Plug-in Helper for Eclipse - [https://docs.asakusafw.com/jinrikisha/ja/html/shafu.html]

Asakusa Frameworkではアプリケーションのビルドに Gradle [http://www.gradle.org/] というビルドシステムを利用しますが、 Shafuを使うことで、Gradleに関する詳細な知識がなくてもAsakusa Frameworkの基本的な開発作業が行えるようになります。また、コマンドライン上でのGradleの操作が不要となり、Eclipse上でアプリケーション開発に必要なほとんどの作業を行うことができるようになります。

なお、このスタートガイドではコマンドライン上でGradleを利用する手順と、Shafuを利用する手順の両方を記載します。

Jinrikisha

Jinrikisha (人力車) は、 Asakusa Framework の開発環境を手軽に構築するためのインストーラパッケージです。

Jinrikisha - Asakusa Framework Starter Package - [https://docs.asakusafw.com/jinrikisha/ja/html/index.html]

Jinrikishaは新規のLinux環境上にAsakusa Framework専用の開発環境を簡単にセットアップすることを主な目的としています。 JDKやEclipseといった基本的なツールのセットアップに加えて、ローカル環境でHadoopやSparkを利用したバッチアプリケーションを実行できるようにするための設定も行うため、 Hadoopクラスターなどの運用環境にデプロイする前にバッチアプリケーションの疎通確認や検証を行うといった用途に適しています。

このスタートガイドではJinrikishaの利用は前提ではありませんが、開発したアプリケーションをローカルで実行したい場合はJinrikishaを使って環境をセットアップすると便利です。

Shafuのセットアップ

Shafuを利用する場合、以下の手順例を参考にしてEclipse上にインストールしてください。

See also

Shafuについては、 Shafuのドキュメント [https://docs.asakusafw.com/jinrikisha/ja/html/shafu.html] も参考にしてください。

Shafuのインストール

ShafuはEclipseプラグインとして公開されており、一般的なEclipseプラグインと同様にインストールを行います。

以下、Eclipse上でのインストール手順例です。

Eclipseのメニューバーから Help ‣ Install New Software… を選択します。

Install ダイアログで Work with: の項目右の Add ボタンを押下します。

Add Repository ダイアログに以下の値を入力します。

Name: 任意の名前(例: Jinrikisha )

Location: http://www.asakusafw.com/eclipse/jinrikisha/updates/

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

以降、画面の指示に従いインストールを進めます。Eclipseの再起動を促されたら Yes を選択します。

Eclipseの再起動が完了したら Java パースペクティブを選択し、 メニューバーから Window ‣ Perspective ‣ Reset Perspective.. を選択して Java パースペクティブを初期化します。

Attention

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

EclipseのJDK登録

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

Eclipseの設定画面から Java ‣ Installed JREs を選択します。

Installed JREs ダイアログにJDK以外のJava定義が表示されている場合 (例えば jre8 のような項目が表示されている場合)、これら項目を削除します。 削除する項目を選択して、 Remove ボタンを押下します。

JDKを追加します。 Installed JREs ダイアログで Add ボタンを押下します。

JRE Type ダイアログで Standard VM を選択し、 Next > ボタンを押下します。

JRE Definition ダイアログで JRE home: の項目右の Directory… ボタンを押下し、JDKのフォルダを指定します。

JRE Definition ダイアログの各項目にインストールしたJDKの情報が設定されたことを確認して Finish ボタンを押下します。

Installed JREs ダイアログに追加したJDKの項目が表示されるので、その項目の Name 欄に表示されているチェックボックスを ON にします。JDKの項目が jdk1.8.0_XX (default) のような表示になれば設定完了です。

Attention

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

環境変数の確認

Eclipse上で環境変数 ASAKUSA_HOME が有効になっていることを確認します。

Eclipseの設定画面から Jinrikisha (人力車) ‣ Asakusa Framework を選択します。

フレームワークのインストール先 (ASAKUSA_HOME) に環境変数 ASAKUSA_HOME で設定したフォルダが表示されていることを確認します。

正しく表示されていない場合、環境の設定を確認してください。

アプリケーション開発の準備

アプリケーションプロジェクトの作成

バッチアプリケーションの開発をはじめるには、まずAsakusa Frameworkアプリケーション開発用のプロジェクトを作成します。

アプリケーションプロジェクトを作成するには、オンライン上に公開されているAsakusa Frameworkのプロジェクトテンプレートを利用すると便利です。このプロジェクトテンプレートにはプロジェクトで利用するビルドツール(Gradle)の設定や実行環境、および開発環境で利用する設定ファイルなどが含まれます。

プロジェクトテンプレートは、以下リンクからダウンロードします。

プロジェクトテンプレートのダウンロード

プロジェクトテンプレート

説明

asakusa-spark-template-0.10.3.tar.gz [http://www.asakusafw.com/download/gradle-plugin/asakusa-spark-template-0.10.3.tar.gz]

Asakusa on Spark を利用するプロジェクトテンプレート

asakusa-m3bp-template-0.10.3.tar.gz [http://www.asakusafw.com/download/gradle-plugin/asakusa-m3bp-template-0.10.3.tar.gz]

Asakusa on M3BP を利用するプロジェクトテンプレート

asakusa-mapreduce-template-0.10.3.tar.gz [http://www.asakusafw.com/download/gradle-plugin/asakusa-mapreduce-template-0.10.3.tar.gz]

Asakusa on MapReduce を利用するプロジェクトテンプレート

コマンドライン上から作成する場合、上記のURLに公開されているプロジェクトテンプレートのアーカイブを展開します。以下は Asakusa on Spark 用のプロジェクトテンプレートを展開する例です。

cd <work-dir>
curl -OL http://www.asakusafw.com/download/gradle-plugin/asakusa-spark-template-0.10.3.tar.gz
tar xf asakusa-spark-template-0.10.3.tar.gz
mv asakusa-spark-template my-batchapp
cd my-batchapp

Shafuを導入した開発環境では、オンライン上に公開されているAsakusa Frameworkのプロジェクトテンプレートカタログを利用して、テンプレートプロジェクトをベースに新規プロジェクトを作成することができます。

Javaパースペクティブ上のメニューバーから File ‣ New ‣ Gradleプロジェクトをテンプレートから生成 を選択します。

新規プロジェクト情報 ダイアログで、プロジェクト名などを入力します。

テンプレートからプロジェクトを作成 ダイアログで URLを指定してプロジェクトテンプレートをダウンロードする が選択状態になっていることを確認して、画面右の 選択 ボタンを押下します。

プロジェクトテンプレート ダイアログにオンラインに公開されている、利用可能なプロジェクトテンプレートの一覧が表示されます。

Asakusa on Spark を利用するプロジェクトテンプレートを利用する場合は、以下を選択します。

Asakusa Project Template <Spark> - <version>

Asakusa on M3BP を利用するプロジェクトテンプレートを利用する場合は、以下を選択します。

Asakusa Project Template <M3BP> - <version>

Asakusa on MapReduce を利用するプロジェクトテンプレートを利用する場合は、以下を選択します。

Asakusa Project Template <MapReduce> - <version>

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

Asakusa Frameworkのインストール

次に、開発環境用のAsakusa Frameworkをインストールします。これはアプリケーションのテスト時などに利用します。

コマンドライン上からインストールする場合、Gradleの installAsakusafw タスクを実行します。プロジェクト上でタスクを実行するには、以下のように gradlew コマンドにタスク名を指定して実行します。

./gradlew installAsakusafw

Shafuを導入した開発環境では、EclipseのメニューからAsakusa Frameworkのインストールを実行します。

Javaパースペクティブ上のプロジェクトを選択してコンテキストメニュー(右クリックなどで表示されるメニュー)を表示します。

コンテキストメニューから Jinrikisha (人力車) ‣ Asakusa開発環境の構成 ‣ Asakusa Frameworkのインストール を選択します。

インストールが成功した場合、コンソールに以下のように表示され、環境変数 ASAKUSA_HOME で指定したフォルダ配下にAsakusa Frameworkがインストールされます。

...
:installAsakusafw
Asakusa Framework is successfully installed: /home/asakusa/asakusa

BUILD SUCCESSFUL

Total time: 4.352 secs

Next Step

ここまでの手順で、Asakusa Framework上でバッチアプリケーションの開発を行う準備が整いました。

次のステップとして、 開発の流れ では実際にアプリケーションの開発を行うための、Asakusa Frameworkを使ったアプリケーション開発の流れを紹介しています。

また Asakusa Framework チュートリアル [https://docs.asakusafw.com/basic-tutorial/0.10/release/ja/html/index.html] では、サンプルアプリケーションを作成しながらフレームワークの基本的な使い方や開発の流れを説明しています。

このスタートガイドの以降の説明では、公開されているサンプルアプリケーションを使ってバッチアプリケーションを実行する手順を紹介しています。

サンプルアプリケーションの実行

ここでは、Asakusa Frameworkのサンプルアプリケーションを使って、Spark環境上でバッチアプリケーションを実行する手順を簡単に説明します。

Spark環境はあらかじめ準備されているものとします。また、入出力ファイルの配置にはHadoopファイルシステムを利用するため、Hadoop環境も合わせて準備されているものとします。

サンプルアプリケーションの概要

Asakusa Frameworkの サンプルプログラム集 (GitHub) [http://github.com/asakusafw/asakusafw-examples] ではいくつかのサンプルアプリケーションが公開されています。その中から、ここでは examle-basic-spark ディレクトリ配下に含まれるサンプルアプリケーション「カテゴリー別売上金額集計バッチ」を使います。

カテゴリー別売上金額集計バッチは、売上トランザクションデータと、商品マスタ、店舗マスタを入力として、エラーチェックを行った後、売上データを商品マスタのカテゴリ毎に集計するアプリケーションです。

バッチアプリケーションの入力データ取得と出力データ生成には、Asakusa Frameworkの「Direct I/O」と呼ばれるコンポーネントを利用しています。 Direct I/Oを利用して、Hadoopファイルシステム上のCSVファイルに対して入出力を行います。

サンプルアプリケーションプロジェクトの作成

サンプルプログラム集 (GitHub) [http://github.com/asakusafw/asakusafw-examples] に公開されているプロジェクトを開発環境に取り込みます。

コマンドライン上でプロジェクトを作成する場合、GitHub上に公開されているサンプルアプリケーションのアーカイブを展開します。

cd <work-dir>
curl -OL https://github.com/asakusafw/asakusafw-examples/archive/0.10.3.tar.gz
tar xf 0.10.3.tar.gz
cd asakusafw-examples-0.10.3/example-basic-spark

Shafuを導入した開発環境では、オンライン上に公開されているAsakusa Frameworkのプロジェクトテンプレートカタログを利用して、サンプルアプリケーションのプロジェクトをEclipse上に取り込みます。

Javaパースペクティブ上のメニューバーから File ‣ New ‣ Gradleプロジェクトをテンプレートから生成 を選択します。

新規プロジェクト情報 ダイアログで、プロジェクト名などを入力します。

テンプレートからプロジェクトを作成 ダイアログで URLを指定してプロジェクトテンプレートをダウンロードする が選択状態になっていることを確認して、画面右の 選択 ボタンを押下します。

プロジェクトテンプレート ダイアログにオンラインに公開されている、利用可能なプロジェクトテンプレートの一覧が表示されます。ここでは以下を選択します。

Asakusa Example Projects - 0.10.3

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

テンプレートからプロジェクトを作成 ダイアログで example-basic-spark を選択して OK ボタンを押下します。

サンプルアプリケーションのビルド

Asakusa Frameworkの開発環境で作成したバッチアプリケーションを運用環境（Hadoopクラスターなど）で実行するには、コンパイル済みのバッチアプリケーションとAsakusa Framework本体の実行モジュールをあわせて運用環境にデプロイします。そのためにまず、開発環境上でデプロイに必要なモジュールを全て含めた「デプロイメントアーカイブ」と呼ばれるパッケージファイルを生成します。

コマンドライン上でデプロイメントアーカイブを生成するには、Gradleの assemble タスクを実行します。

./gradlew assemble

Shafuを導入した開発環境では、コンテキストメニューから Jinrikisha (人力車) ‣ Asakusaデプロイメントアーカイブを生成 を選択します。

このコマンドの実行によって、アプリケーションプロジェクトに対して以下の処理が実行されます。

データモデル定義DSL(DMDL)から、データモデルクラスを生成

Asakusa DSLとデータモデル定義DSLから、HadoopやSparkなどの各処理系で実行可能なプログラム群を生成

アプリケーションを実行環境に配置するためのデプロイメントアーカイブファイルを生成

デプロイメントアーカイブファイルはプロジェクトの build ディレクトリ配下に asakusafw-example-basic-spark.tar.gz というファイル名で生成されます。

サンプルアプリケーションのデプロイ

サンプルアプリケーションのビルド で作成したデプロイメントアーカイブファイルを運用環境にデプロイします。

通常、デプロイ対象となるノードはHadoopやSparkのクライアントモジュールがインストールされているノードを選択します。

以降の手順を行う前に、デプロイメントアーカイブファイル asakusafw-example-basic-spark.tar.gz をデプロイ対象となるノードに転送しておいてください。

環境変数の設定

運用環境上でAsakusa Frameworkを配置しバッチアプリケーションを実行するためのOSユーザーに対して、以下の環境変数を設定します。

JAVA_HOME: Javaのインストールパス

SPARK_CMD: spark-submit コマンドのパス

ASAKUSA_HOME: Asakusa Frameworkのインストールパス

以下は環境変数の設定例です。

export JAVA_HOME=/usr/lib/jvm/java-8-oracle
export SPARK_CMD=/opt/spark/bin/spark-submit
export ASAKUSA_HOME=$HOME/asakusa

デプロイメントアーカイブの展開

サンプルアプリケーションのビルド で作成したデプロイメントアーカイブファイル asakusafw-example-basic-spark.tar.gz を配置し、 $ASAKUSA_HOME 配下にデプロイメントアーカイブを展開します。展開後 $ASAKUSA_HOME/tools/bin/setup.jar を実行し、展開したファイルに対して適切な実行権限などを設定します。

mkdir -p "$ASAKUSA_HOME"
cd "$ASAKUSA_HOME"
tar -xzf /path/to/asakusafw-example-basic-spark.tar.gz
java -jar $ASAKUSA_HOME/tools/bin/setup.jar

サンプルデータの配置

サンプルアプリケーションの構成では、 $ASAKUSA_HOME/example-dataset ディレクトリ以下にテスト用の入力データが用意されています。これらのファイルをHadoopファイルシステム上のDirect I/Oの入出力ディレクトリ(デフォルトの設定では target/testing/directio 配下) にコピーします。

Warning

Direct I/Oの出力ディレクトリはバッチアプリケーション実行時に初期化されます。既存のディレクトリを利用する場合、このパスに重要なデータがないことを実行前に確認してください。

以下は、サンプルデータをHadoopファイルシステムに配置する手順の例です。

hadoop fs -mkdir -p target/testing/directio
hadoop fs -put $ASAKUSA_HOME/example-dataset/master target/testing/directio/master
hadoop fs -put $ASAKUSA_HOME/example-dataset/sales target/testing/directio/sales

サンプルアプリケーションの実行

サンプルアプリケーションを実行します。

Asakusa Frameworkでは、バッチアプリケーションを実行するためのコマンドプログラムとして「YAESS」というツールが提供されています。バッチアプリケーションを実行するには、$ASAKUSA_HOME/yaess/bin/yaess-batch.sh に実行するバッチのバッチIDとバッチ引数を指定します。

サンプルアプリケーション「カテゴリー別売上金額集計バッチ」は「 example.summarizeSales 」というバッチIDを持っています。また、このバッチは引数に処理対象の売上日時( date )を指定し、この値に基づいて処理対象CSVファイルを特定します。

Sparkを利用するバッチアプリケーションは、Spark向けのバッチアプリケーションはバッチIDの接頭辞に spark. を付与して実行します。

$ASAKUSA_HOME/yaess/bin/yaess-batch.sh spark.example.summarizeSales -A date=2011-04-01

バッチの実行が成功すると、コマンドの標準出力の最終行に Finished: SUCCESS と出力されます。

...
2016/03/17 03:56:24 INFO  [YS-CORE-I01999] Finishing batch "spark.example.summarizeSales": batchId=spark.example.summarizeSales, elapsed=51,738ms
2016/03/17 03:56:24 INFO  [YS-BOOTSTRAP-I00999] Exiting YAESS: code=0, elapsed=51,790ms
Finished: SUCCESS

サンプルアプリケーション実行結果の確認

Asakusa FrameworkはDirect I/Oの入出力ディレクトリやファイルの一覧をリストアップするコマンド $ASAKUSA_HOME/directio/bin/list-file.sh を提供しています。このコマンドを利用して、サンプルアプリケーションの出力結果を確認します。

ここでは、サンプルアプリケーションの出力結果ディレクトリ result 以下のすべてのファイルを、サブディレクトリ含めてリストするようコマンドを実行してみます。

$ASAKUSA_HOME/directio/bin/list-file.sh result "**/*"

上記のコマンドを実行すると、以下のような結果が表示されます。

Starting List Direct I/O Files:
...
hdfs://<host:port>/user/asakusa/target/testing/directio/result/category
hdfs://<host:port>/user/asakusa/target/testing/directio/result/error
hdfs://<host:port>/user/asakusa/target/testing/directio/result/category/result.csv
hdfs://<host:port>/user/asakusa/target/testing/directio/result/error/2011-04-01.csv

出力ファイルの一覧に対して、 hadoop fs -text コマンドを利用してファイル内容を確認します。

以下は 売上データの集計ファイル category/result.csv を表示する例です。

hadoop fs -text hdfs://<host:port>/user/asakusa/target/testing/directio/result/category/result.csv

指定したファイルの内容が表示されます。売上データが商品マスタのカテゴリコード単位で集計され、売上合計の降順で整列されたCSVが出力されています。

category/result.csv

カテゴリコード,販売数量,売上合計
1600,28,5400
1300,12,1596
1401,15,1470

また、このバッチでは処理の中で不正なレコードをチェックして、該当したエラーレコードをまとめてファイル error/2011-04-01.csv に出力します。

hadoop fs -text hdfs://<host:port>/user/asakusa/target/testing/directio/result/error/2011-04-01.csv

エラーチェックに該当したレコードの一覧は以下のように出力されます。

error/2011-04-01.csv

ファイル名,日時,店舗コード,商品コード,メッセージ
hdfs://<host:port>/user/asakusa/target/testing/directio/sales/2011-04-01.csv,2011-04-01 19:00:00,9999,4922010001000,店舗不明
hdfs://<host:port>/user/asakusa/target/testing/directio/sales/2011-04-01.csv,2011-04-01 10:00:00,0001,9999999999999,商品不明
hdfs://<host:port>/user/asakusa/target/testing/directio/sales/2011-04-01.csv,1990-01-01 10:40:00,0001,4922010001000,商品不明

開発の流れ

この文書では、はじめてAsakusa Frameworkを使ったバッチアプリケーションを開発するユーザー向けに、Asakusa Frameworkを使った開発の流れを紹介します。

Asakusa Frameworkを使ったアプリケーションの開発の流れの概要を、下図に示します。

アプリケーションの設計

本書では設計については、Asakusa Frameworkに直接関係あるトピックに対してのみ、その概要を簡単に説明します。バッチの運用設計やシステムアーキテクチャ設計などについては、本書では説明しません。

バッチ処理一覧

あるシステムに対して提供されるバッチの一覧とその概要を洗い出します。ここから、ユーザーが実行するバッチの単位（もしくは、ワークフローエンジンやYAESSなどのバッチを実行するためのツールが認識する単位）を決定します。

Asakusa Frameworkでは、このバッチの実行単位毎にAsakusa DSLの最上位のDSLであるバッチDSLを作成し、固有のIDを設定します。

外部インターフェース

バッチアプリケーションは何かしらの外部システムから処理対象データを入力し、また実行結果を外部システムに出力します。ここでは連携する外部システムとの入出力方式に関する検討を行います。

Asakusa Frameworkには、Hadoopが管理する分散ファイルシステム上に配置したデータに対して、 Direct I/O というデータ入出力機能を利用してデータを読み書きすることができます。

Direct I/OはHadoopを利用する上での様々な最適化機構を備えており、またデータ入出力に外部システム連携ツールを経由しないため高速に動作するというメリットがある反面、データの投入や保全などの運用面を個別に考える必要があります。

また、Asakusa Frameworkには、外部システムと連携するためのツールとして WindGate という外部システム連携ツールが標準で同梱されています。

WindGateは「ポータブルなデータ転送ツール」を目指したもので、さまざまなRDBMSやローカルファイルシステム上のフラットファイルなどを利用できますが、特定環境向けの最適化を行っておらず、大容量データの入出力には不向きです。

以下はフラットファイルをデータの入出力に利用する際に、Direct I/OとWindGateの特性を比較したものです。

外部システム連携の比較 (フラットファイル)

特徴

Direct I/O

WindGate

メリット

Hadoopの性能を生かして高速に動作する

ファイルストレージとHadoopを柔軟な構成で配置して利用できる

デメリット

ファイルをHadoopから直接参照できる場所に配置する必要がある

Direct I/Oに性能面で劣る

以上を考慮して、バッチ処理のデータ入出力に利用する構成を検討します。

また、バッチ処理が失敗したときのロールバック、リカバリーの単位などを考慮しながら、外部システムと連携して一連の処理を行う単位と、この単位で入力および出力を行うデータを決定します。 Asakusa Frameworkではこの処理単位を「ジョブフロー」として定義します。

また、Asakusa Frameworkでは、入力データに対してそのデータサイズを指定することで処理の最適化を行う仕組みが提供されているため、この時点でおおよその入力データの種類毎のデータサイズを把握しておくとよいでしょう。

データフロー記述

あるデータに対する処理について、入力となるデータ、入力データに対する処理の内容、出力となるデータを定義し、その流れを記述します。

Asakusa Frameworkでは、バッチの処理をデータフローの形式で記述します。そのため、バッチ処理の流れを設計する際にも、あらかじめデータフローに近い形式で記述しておくのがよいでしょう。それぞれのデータフローでは、入力された（複数の）データをどのように加工して、最終的にどこに出力するかということを記述します。

データを加工する部分は、Asakusa Frameworkでは「演算子」として実装することになります。演算子には、データの内容を書きかえるような単純なものや、複数のデータの流れを特定のプロパティでグループ化し、さらにそれらのグループを結合するような複雑なものもあります。

Asakusa Frameworkではデータフローの一部を共通化して、データフローを部品化して扱うことも出来ます。 Asakusa Frameworkでは、共通化されたデータフロー部品を「フロー部品」と呼びます。データフローを記述する際にはこういった点も考慮するとよいでしょう。

データモデル定義

バッチアプリケーションが扱う入力データ、出力データの項目レベルの定義を行います。

外部システムとの連携がDBMSの場合はデータベースのE/R設計、ファイルによる連携の場合はファイルフォーマットに合わせて定義することになるでしょう。

アプリケーションの実装

Asakusa Frameworkを使ったバッチアプリケーションの実装の流れを見ていきます。

アプリケーションプロジェクトの作成とビルド

バッチアプリケーションのソースコード一式を作成・管理するためのプロジェクトを作成します。

Asakusa Gradle Plugin ユーザーガイド には、アプリケーションプロジェクトの作成やビルドに関する内容が記載されています。

データモデル定義DSLの記述

データモデル定義に基づいて、Asakusa Frameworkが提供するデータモデル記述言語(DMDL)を記述します。また、記述したDMDLからデータモデルクラスを自動生成します。作成したデータモデルクラスは、後述するAsakusa DSLで処理の入力、及び出力対象のオブジェクトとして利用します。

DMDLスタートガイド には、DMDLの記述およびデータモデルクラスの作成に関する基本的な内容が記載されています。

Asakusa DSLの記述

Asakusa Frameworkでアプリケーションを作成するには、 Asakusa DSLで処理の内容やデータフロー、データの入出力方式を定義します。

Asakusa DSLでは、データフローの最小単位で、主にデータの加工を行う演算子（Operator DSL）の記述、演算子を組み合わせてデータフローの構造を記述し、外部システムとの入出力データ定義を行うジョブフロー/フロー部品（Flow DSL）、バッチの構造の記述（Batch DSL）をそれぞれ行います。

Asakusa DSLスタートガイド には、Asakusa DSLの記述に関する基本的な内容が記載されています。

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

Asakusa Frameworkは、Asakusa DSLの単位でテストを行うための仕組みが提供されています。

Operator DSLついては、一般的なクラスに対する単体テストと同様の方法でテストを作成することができます。 Flow DSLおよびBatch DSLについては、DSLのコンパイラや実行環境と連携してテストを実行するテストドライバーという機能を利用してテストを作成します。

テストドライバーを利用したテストでは、テストドライバーAPIを使って実装するテストクラス、およびテストデータとしてテストの入力データ、テストの期待データ、期待結果と実行結果との検証ルールを作成します。テストドライバーではテストデータを様々なファイル形式やプログラムとして作成するための豊富な機能を提供しています。

アプリケーションテストスタートガイド には、アプリケーションのテストに関する基本的な内容が記載されています。

外部システム連携

Asakusa DSLのジョブフローについては、外部システムとの連携についての定義を行います。また、アプリケーションのテストを行う際に、外部システム連携の構成によっては外部システム連携モジュールに適切な設定を行う必要があります。

外部システム連携モジュールの利用方法については、以下のドキュメントを参照してください。

Direct I/O スタートガイド

WindGateスタートガイド

運用環境の構築とアプリケーションの実行

開発したバッチアプリケーションを運用環境（Hadoopクラスター、及び外部システムとの連携）で実行する準備を行います。運用環境の構築については、以下のドキュメントを参照してください。

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

運用環境の構築が完了したら、バッチアプリケーションを実行してみましょう。

Asakusa CLI ユーザーガイド や YAESSスタートガイド には、Asakusa Frameworkが提供するバッチ実行ツールの基本的な説明が記載されています。

アプリケーションの実装 - Asakusa Data Model

DMDLの特徴

Data Model Definition Language (DMDL)は、Asakusa Frameworkで利用するJavaのデータモデルクラスを定義するための言語です。 DMDLではそれぞれのデータモデルが持つプロパティなどを定義でき、DMDLで定義されたデータモデルをDMDLコンパイラに渡すと、対応したJavaのデータモデルクラスを自動的に作成します。

Asakusa Framewokを利用する場合、DMDLを利用してデータモデルを作成することが推奨されます。これは、次のような理由があります。

Asakusa DSLとの連携

Hadoopの連携

他システムとの連携

Asakusa DSLとの連携

Asakusa DSLの内部で利用するデータモデルは、DSLのコンパイルの途中で内部的に別のデータ構造に分解されます。 DMDLで生成したデータモデルには、コンパイラに必要なメタ情報が自動的に作成されます。

Hadoopの連携

Hadoopは独自のWritableというインターフェースを利用したオブジェクトの直列化機構を利用しています。 DMDLで生成したデータモデルは、この直列化機構を利用するための機能を自動的に提供します。

他システムとの連携

DMDLコンパイラは外部システムとの連係情報を自動的に生成するためのプラグイン機構を提供しています。 DMDLを中心としてデータモデルを定義することで、Direct I/OやWindGateなどの外部システム連携機能と整合性を保ちながらデータモデルを管理できます。

関連するドキュメント

DMDLスタートガイド

DMDLユーザーガイド

DMDL開発者ガイド

DMDLスタートガイド

この文書では Asakusa Framework スタートガイド の構成で、DMDLを使ってJavaのデータモデルクラスを生成する方法について簡単に紹介します。

See also

DMDLの詳しい記述方法を知りたい場合や、コマンドライン等からDMDLを利用したい場合には、 DMDLユーザーガイド を参照してください。

DMDLを記述する

Data Model Definition Language (DMDL)はAsakusa Frameworkで利用可能なデータモデルを定義するためのDSLです。 DMDLスクリプトというファイルにデータモデルの名前や構造を定義し、DMDLコンパイラを実行することで、定義したデータモデルに対応するJavaのプログラムを自動的に生成します。

DMDLスクリプトを作成する

Asakusa Framework スタートガイド の流れに従ってプロジェクトを作成した場合、DMDLスクリプトはプロジェクトの src/main/dmdl ディレクトリ以下に配置してください。また、スクリプトのファイル名には .dmdl の拡張子を付けて保存してください。

データモデルを定義する

データモデルを新たに定義するには、作成したDMDLスクリプト内に <データモデル名> = <プロパティ定義>; のように記述します。

model_name = {
    property_name : INT;
};

ここでは、以下の点に注意してください。

データモデル名やプロパティ名はすべて小文字で指定し、単語区切りにアンダースコアを利用する

プロパティの型は、プロパティ名の右側にコロンをはさんで大文字で指定する

データモデルやプロパティの末尾にはセミコロンを指定する

データモデル内に複数のプロパティを定義するには、 { と } の間にプロパティを続けて指定します。

model_name = {
    property_name : INT;
    second_property : TEXT;
    third : DOUBLE;
};

複数のデータモデルを定義するには、DMDLスクリプト内にデータモデルを続けて記述します。

model_name = {
    property_name : INT;
};
second_model = {
    prop : LONG;
};
third = {
    other : DATE;
};

Tip

DMDLスクリプトファイルを複数用意し、それぞれのファイルにデータモデルクラスを定義することも可能です。

利用可能なプロパティの種類

それぞれのプロパティには下記のいずれかの型を指定できます。

DMDLとJavaのデータ型

型の名前

対応するJavaの型

INT

IntOption

LONG

LongOption

FLOAT

FloatOption

DOUBLE

DoubleOption

TEXT

StringOption

DECIMAL

DecimalOption

DATE

DateOption

DATETIME

DateTimeOption

BOOLEAN

BooleanOption

BYTE

ByteOption

SHORT

ShortOption

複数のデータモデルを合成する

DMDLでは、定義した複数のデータモデルを組み合わせて新しいデータモデルを定義できます。

both = left + right;
left = {
    left_value : INT;
};
right = {
    right_value : TEXT;
};

上記のようにデータモデル定義の右辺で「モデル名 + モデル名」と記述した場合、それぞれのデータモデルで定義したプロパティをすべて持つような新しいデータモデルを定義します。この例では、以下のようなデータモデルを定義したことになります。

both = {
    left_value : INT;
    right_value : TEXT;
};

なお、3つ以上のデータモデルを組み合わせることも可能です。

データモデルを拡張する

以下のように他のデータモデルと新しいプロパティを合成して、新しいデータモデルを定義できます。

origin = {
    value : INT;
};
extended = origin + {
    extra : TEXT;
};

上記の extended では、 origin で定義したプロパティ value に加えて、新たに extra というプロパティを定義しています。この extended は以下のような構造になります。

extended = {
    value : INT;
    extra : TEXT;
};

このようにDMDLでは、他のデータモデルの定義や新たなプロパティの定義を組み合わせて、複雑なデータモデルを定義できます。

データモデルクラスを生成する

DMDLコンパイラの起動

DMDLスクリプトに記述したデータモデルからJavaのデータモデルクラスを生成するには、Gradleを利用してDMDLコンパイラを実行します。

これはGradleの compileDMDL タスクで起動するので、プロジェクト内で以下のようにコマンドを実行します。

./gradlew compileDMDL

その他、 compileJava タスクや build タスクなどでも自動的にDMDLコンパイラが起動します。

Direct I/Oとの連携

Asakusa Framework スタートガイド の構成では、Direct I/Oと連携したバッチアプリケーションを作成できます。

Direct I/Oを利用するプロジェクト構成の場合、Direct I/Oに関するデータ変換を行うプログラムをDMDLから自動生成できます。詳しい情報は データの直接入出力 - Direct I/O を参照してください。

WindGateとの連携

WindGateとの連携について、詳しい情報は 外部システムとの連携 - WindGate を参照してください。

DMDLユーザーガイド

この文書では、Data Model Definition Language (DMDL)およびDMDLコンパイラの利用方法について紹介します。

DMDLの記述

DMDLを利用してデータモデルを定義するには、「DMDLスクリプト」というファイルの中に、データモデルの名前やプロパティの構造を記述します。 DMDLスクリプトは拡張子を .dmdl としたUTF-8エンコーディングのテキストファイルで、一つのDMDLスクリプトに複数のデータを定義することも、複数のDMDLスクリプトを利用して必要なデータモデル一式を定義することもできます。

DMDLでは4種類のデータモデルを記述できます。

レコードモデルを定義する

結合モデルを定義する

集計モデルを定義する

射影モデルを定義する

レコードモデルを定義する

レコードモデルはプロパティの一覧を持つデータ構造です。

レコードモデルを定義するには、DMDLスクリプトに次のように記述します。

<モデル名> = {
    <プロパティの一覧>
};

それぞれのプロパティは、プロパティ名のあとにプロパティの型を指定します。また、一つのレコードモデルには複数のプロパティを定義できます。

<プロパティの名前> : <プロパティの型> ;

モデル名やプロパティ名の形式については 名前の形式 を、プロパティに利用可能な型は プロパティの型 を参照して下さい。

以下はモデル名が example_model 、プロパティがそれぞれ整数型の number , 文字列型の item_code , 日時型の last_updated である場合の記述です。

example_model = {
    number : INT;
    item_code : TEXT;
    last_updated : DATETIME;
};

名前の形式

データモデルやプロパティの名前は、次のような snake_case の形式でなければなりません。

小文字のアルファベット、数字、アンダースコアのみ

最初の文字と最後の文字にアンダースコアを使えない

アンダースコアを2つ以上続けて使えない

_option で終わるプロパティ名を使えない

また、以下の条件を満たすことを強く推奨しています。

名前にはJavaの予約語を利用しない

名前に含まれる各単語はアルファベットから始める(数字や記号から始めない) 1

以下に名前の指定例を示します。

よい例

hello

good_model_name

better1

悪い例

helloWorld

BAD_PROPERTY_NAME

worse_0

1

名前の各単語を数字から始めた場合、ある条件下でテストドライバーの一部機能に問題が発生することが報告されています。

プロパティの型

それぞれのプロパティには次のような型を指定できます。

利用可能なプロパティの型

型の名前

説明

INT

32bit符号付き整数

LONG

64bit符号付き整数

FLOAT

単精度浮動小数点

DOUBLE

倍精度浮動小数点

TEXT

文字列

DECIMAL

10進数

DATE

日付

DATETIME

日時

BOOLEAN

論理値

BYTE

8bit符号付き整数

SHORT

16bit符号付き整数

データモデルを合成する

他で定義したデータモデルを合成して新しいレコードモデルを作成するには、次のように記述します。

<定義するモデルの名前> = <合成するモデル1> + <合成するモデル2> + ... ;

合成されたデータモデルは、対象のデータモデルが定義する全てのプロパティを持つことになります。

both = left + right;
left = {
    left_value : INT;
};
right = {
    right_value : TEXT;
};

上記の例では、以下のようなデータモデルを定義したことになります。

both = {
    left_value : INT;
    right_value : TEXT;
};

なお、合成するそれぞれのモデルが同じプロパティを定義している場合、そのプロパティは一つだけ定義されたことになります。また、同じ名前で型が異なるプロパティが定義された場合、データモデルの合成は失敗してエラーになります。

データモデルを拡張する

他のデータモデルに新たにプロパティを追加したデータモデルを定義するには、次のように記述します。

<モデル名> = <対象のモデル> + ... + {
    <プロパティの一覧>
};

拡張されたデータモデルは、対象のデータモデルが定義するすべてのプロパティに加え、新たに定義したプロパティを持つことになります。

origin = {
    value : INT;
};
extended = origin + {
    extra : TEXT;
};

上記の例では、以下のようなデータモデルを定義したことになります。

extended = {
    value : INT;
    extra : TEXT;
};

このようにDMDLでは、他のデータモデルの定義や新たなプロパティの定義を組み合わせて、複雑なデータモデルを定義できます。

結合モデルを定義する

結合モデルは、2つのデータモデルに「結合」の操作を行って生成するデータモデルを表します。出来上がるデータモデルはレコードモデルと同様に複数のプロパティを持つデータ構造ですが、Asakusa DSLの「マスタ結合演算子」で利用した際に結合条件などの情報を自動的に取り出せます。

結合モデルの定義で記述する情報は、以下の通りです。

結合対象のデータモデル

結合条件 (等価結合条件のみ)

結合前後でのプロパティのマッピング

プロパティマッピングを行わない場合、次のような方法で結合モデルを定義します。

joined <結合モデル名> = <対象モデル1> % <結合キー1> + <対象モデル2> % <結合キー2>;

それぞれの 対象モデル には、他で定義したデータモデルの名前を指定します。また、それぞれの 結合キー には、対象モデルに含まれるプロパティの名前をカンマ区切りで指定します。

上記の形式で定義した結合モデルは、それぞれの対象モデルに定義された全てのプロパティを持ち、それぞれの結合キーを順に等価比較して結合するような構造を表します。

たとえば、次のような結合モデル item_order を定義できます。

item = {
    code : LONG;
    id : TEXT;
    ...
};
order = {
    item_code : LONG;
    item_id : TEXT;
    ...
};
joined item_order = item % code, id + order % item_code, item_id;

定義された結合モデルは、 item と order が定義する全てのプロパティを持ち、 item.code = order.item_code かつ item.id = order.item_id という条件で結合可能であることを表す構造になります。

この結合モデル定義の形式は記述が簡潔ですが、対象モデル間に同一のプロパティ名が含まれている場合は利用出来ません。また、不要なプロパティもすべて含むデータモデルが生成されることに注意が必要です。これらの問題を回避するためには、以下に示す プロパティのマッピング を利用して結合モデルを定義します。

プロパティのマッピング

結合時に不要なプロパティを削除したりプロパティの名前を変えるには、結合モデルの定義時にプロパティのマッピングを記述します。

joined <結合モデル名> = <対象モデル1> -> {
    <プロパティのマッピング1>
} % <結合キー1> + <対象モデル2> -> {
    <プロパティのマッピング2>
} % <結合キー2>;

プロパティのマッピングは、 <元のプロパティ名> -> <マッピング後のプロパティ名> ; の形式でいくつでも書けます。また、マッピングを記述しなかったプロパティについては、結合後のデータモデルから除外されます。

Attention

プロパティのマッピングを利用する場合、結合キーは マッピング後の プロパティ名を指定する必要があります。また、結合キーになるプロパティはマッピングで削除してはいけません。

以下はプロパティのマッピングを行いながら結合モデルを定義する例です。

item = {
    code : LONG;
    price : DECIMAL;
};
order = {
    item_code : LONG;
    amount : INT;
    datetime : DATETIME;
};
joined item_order = item -> {
    code -> code;
    price -> price;
} % code + order -> {
    item_code -> code;
    amount -> total;
} % code;

上記の例で、 item_order にはそれぞれ code , price , total という3つのプロパティが定義されます。それぞれのプロパティには、順に結合前の item.code ( = order.item_code ) , item.price , order.amount の値がマッピングされます。なお、 order.datetime は結合時に捨てられます。

Hint

結合キーに指定されたプロパティは、他の結合キーに指定されたプロパティと同じ名前にできます。結合キーは等価結合に使われるので、常に同じ値になるためです。

結合キーの制約

結合モデルを定義する際に、それぞれの結合キーは次の制約をすべて満たす必要があります。

結合キーに指定したプロパティの個数が一致する

結合キーに指定したプロパティは、対応するものごとに同じ順序で並んでいる

結合キーに指定したプロパティは、対応するものごとに同じ型である

集計モデルを定義する

集計モデルは、1つのデータモデルに「集計」の操作を行って生成するデータモデルを表します。出来上がるデータモデルはレコードモデルと同様に複数のプロパティを持つデータ構造ですが、Asakusa DSLの「単純集計演算子」で利用した際にグループ化条件や集約関数などの情報を自動的に取り出せます。

集計モデルの定義で記述する情報は、以下の通りです。

集計対象のデータモデル

グループ化条件

集計方法

次のような方法で集計モデルを定義します。

summarized <集計モデル名> = <対象モデル> => { <集計方法> } % <グループ化キー> ;

対象モデル には、他で定義したデータモデルの名前を指定します。グループ化キー には集計対象のグループ化に利用するプロパティ名を指定します。

集計方法 は、次のような形式でいくつでも指定できます。

<集約関数> <集計対象のプロパティ名> -> <集計結果のプロパティ名> ;

集計対象のプロパティは、グループ化キーで指定された値ごとにまとめられ、集約関数を適用した上で集計結果のプロパティに格納されます。利用可能な集約関数は、 集約関数の種類 を参照して下さい。

Attention

グループ化キーは 集計結果の プロパティ名を指定する必要があります。また、グループ化キーに指定するプロパティは、 any という集約関数のみを指定できます。

たとえば、次のような集計モデル item_order を定義できます。

order = {
    item_code : LONG;
    price : DECIMAL;
    ...
};
summarized order_summary = order => {
    any item_code -> code;
    sum price -> total;
    count item_code -> count;
} % code;

上記の例で、 order_summary にはそれぞれ code , total , count という3つのプロパティが定義されます。集計は order.item_code ごとに行われ、それぞれのプロパティには、順に order.item_code の値 , order.price の合計 , 集計した個数がマッピングされます。

Hint

レコードの個数を計測する count には、グループ化キーになるプロパティを指定すれば、グループの個数を正しく計測できます。

集約関数の種類

次のような集約関数を利用できます。

集約関数

性質

any

グループ化した中のいずれか一つの値を利用する

sum

グループ化した中の値の合計を利用する

max

グループ化した中の最大値を利用する

min

グループ化した中の最小値を利用する

count

グループ化した中の個数を利用する

集約関数の型マッピング

集約関数を利用した場合、その結果のプロパティ型は以下のように設定されます。 = は集計元と集計結果でプロパティの型が同じであることを示します。

集計元の型

any

sum

max

min

count

BYTE

=

LONG

=

=

LONG

SHORT

=

LONG

=

=

LONG

INT

=

LONG

=

=

LONG

LONG

=

LONG

=

=

LONG

DECIMAL

=

DECIMAL

=

=

LONG

FLOAT

=

DOUBLE

=

=

LONG

DOUBLE

=

DOUBLE

=

=

LONG

BOOLEAN

=

N/A

=

=

LONG

DATE

=

N/A

=

=

LONG

DATETIME

=

N/A

=

=

LONG

TEXT

=

N/A

=

=

LONG

射影モデルを定義する

射影モデルは、他のモデルの一部を投影するデータモデルです。射影モデル自体は実体のデータを持たず、他のデータモデルから「射影」として切り出した際のデータ構造を表します。

射影モデルは、Asakusa DSLの 多相データフロー 機能と組み合わせて利用します。多相データフローは、Asakusa DSLで複数のデータモデルに対する共通の処理をまとめて定義するための記述方法です。詳しくは 多相データフロー を参照してください。

射影モデルを定義するには、 projective というキーワードに続けてレコードモデルと同じ方法でプロパティを定義します。

projective <モデル名> = {
    <プロパティの一覧>
};

プロパティの定義方法は、レコードモデルの「 データモデルを合成する 」や「 データモデルを拡張する 」と同様に、他のデータモデルのプロパティ定義を利用することも可能です。

データモデルに射影を登録する

レコードモデルから射影を取り出すには、対応する射影モデルをレコードモデルにあらかじめ登録しておく必要があります。

レコードモデルに射影モデルを登録するには、レコードモデルの定義時に登録したい射影モデルを合成します。

<レコードモデル名> = <射影モデル> + ... ;

射影モデルを合成してレコードモデルを定義した場合、通常のデータモデルを合成した際と同様に、全てのプロパティが定義するレコードモデルに取り込まれます。

projective proj_model = {
    value : INT;
};

上記のように記述した場合、 proj_model に対応するJavaのデータモデルクラスは生成されず、代わりに同様のプロパティを持つインターフェースが生成されます。このインターフェースを実装( implements )するデータモデルクラスを生成するには、次のようにデータモデル定義の右辺にこの射影モデルを利用します。

conc_model = proj_model + {
    other : INT;
};

射影モデルをデータモデル定義の右辺に利用した場合、その射影モデルが定義するプロパティは、左辺のデータモデルにも自動的に追加されます。さらに、左辺のデータモデルは右辺に利用したすべての射影モデルをインターフェースとして実装します。

また、射影モデルに別の射影モデルを登録することもできます。他の射影を持つ射影モデルをデータモデルに登録した場合、データモデルには関係する全ての射影がとりこまれます。

たとえば、以下の例で record は、 sub_proj , super_proj がどちらも射影として登録されます。

projective super_proj = { a : INT; };
projective sub_proj = super_proj + { b : INT; };
record = sub_proj;

プロパティ参照を定義する

レコードモデルおよび射影モデルには、複数のプロパティを単一のコレクションとして利用するための「プロパティ参照」を定義できます。

これらは固定長のリスト (java.util.List) またはマップ (java.util.Map) として利用でき、それぞれの要素はデータモデル内に存在するプロパティの参照を表します。つまり、データモデル中のプロパティの値を変更するとリストやマップの値も変化し、リストやマップに対して変更を行うと、対応するプロパティの値が変化します。

このプロパティ参照を上手に利用すると、データモデル内に存在する「プロパティの繰り返し」を容易に処理できるようになります。

リスト型のプロパティ参照を定義する

リスト型のプロパティ参照を定義するには、データモデル内に <参照名> = {<参照先のプロパティ名>, ...} の形式で記述します。

m = {
    a : INT;
    b : INT;
    c : INT;
    ref = {a, b, c};
};

上記のように記述した場合、 INT 型のプロパティ a, b, c の他に、 ref という名前のリスト型プロパティ参照を定義します。このとき、それぞれのプロパティは同じ型である必要があります。

この ref は要素にそれぞれ a, b, c の参照を持つ、固定長のリストです。 Javaにおける表現は プロパティ参照の対応付け を参照してください。

マップ型のプロパティ参照を定義する

マップ型のプロパティ参照を定義するには、データモデル内に <参照名> = {<キー> : <参照先のプロパティ名>, ...} の形式で記述します。ただし、それぞれのキーは文字列リテラルの形式でなければなりません。

m = {
    a : INT;
    b : INT;
    c : INT;
    ref = {
        "A" : a,
        "B" : b,
        "C" : c,
    };
};

上記のように記述した場合、 INT 型のプロパティ a, b, c の他に、 ref という名前のマップ型プロパティ参照を定義します。このとき、それぞれのプロパティは同じ型である必要があります。

この ref という要素にそれぞれ a, b, c の参照を持ち、それぞれ文字列 A, B, C のキーが対応づけられた固定長のマップです。 Javaにおける表現は プロパティ参照の対応付け を参照してください。

コメントの挿入

DMDLスクリプトにコメントを挿入するには、以下のように記述します。

-- または // 以下に続く文字列は改行されるまでコメントとみなされます。

/* と */ で囲まれたブロックはコメントとみなされます。これは複数行にわたり有効です。

以下コメントの使用例です。

item = {
    code : LONG; -- XYZコード体系で表現される商品コード
    id : TEXT;
//  name : TEXT;
};

/*
order = {
    item_code : LONG;
    item_id : TEXT;
    name : TEXT;
};
*/

上記では item の code プロパティの追加説明にコメントを使用しています。また、 name はコメントアウトされているため無効になっています。 order はモデル定義の全体がコメントアウトされ無効になっています。

DMDLコンパイラの実行

作成したDMDLスクリプトからAsakusa DSLで利用可能なデータモデルを生成するには、DMDLコンパイラを利用します。

データモデルクラスの生成

DMDLスクリプトからJavaデータモデルクラスを生成する場合、Asakusa Frameworkの asakusa-dmdl-java-*.jar の com.asakusafw.dmdl.java.Main [https://docs.asakusafw.com/0.10.3/release/api/com/asakusafw/dmdl/java/Main.html] クラスを次の引数で起動します。

-output

出力先のディレクトリ

-package

生成するクラスのベースパッケージ名

-source

コンパイルするDMDLスクリプトやディレクトリ

-sourceencoding

DMDLスクリプトのエンコーディング (default: UTF-8)

-targetencoding

生成するJavaのエンコーディング (default: UTF-8)

-plugin

DMDLコンパイラのプラグインファイル (default: なし)

Note

-plugin で指定するコンパイラプラグインについては、 DMDLコンパイラプラグインの利用 も参照してください。

Javaクラスの対応付け

DMDLコンパイラは、DMDLで定義されたデータモデルごとに、対応するJavaのクラスやインターフェースを生成します。

生成するクラスやインターフェースは、次のような名前になります。

<ベースパッケージ名> . <名前空間> . model . <データモデル名>

ベースパッケージ名

DMDLコンパイラに指定したパッケージ名。

名前空間

「 データモデルの名前空間 」で指定した名前。デフォルトは dmdl 。

データモデル名

DMDLスクリプトで定義したデータモデル名を、CamelCaseの形式 2 に変換したもの。

2

例: hello_world -> HelloWorld

プロパティの対応付け

DMDLコンパイラが生成するJavaのクラスやインターフェースには、データモデルに定義したプロパティごとに次の名前の公開メソッドがそれぞれ作成されます。

get <プロパティ名>

set <プロパティ名>

get <プロパティ名> Option

set <プロパティ名> Option

また、 TEXT 型のプロパティに限り、追加で下記の公開メソッドが作成されます

get <プロパティ名> AsString

set <プロパティ名> AsString

それぞれのプロパティの型は、次のようなJavaのデータ型に対応します。

DMDLとJavaのデータ型

型の名前

対応する型 (Option)

INT

int (IntOption)

LONG

long (LongOption)

FLOAT

float (FloatOption)

DOUBLE

double (DoubleOption)

TEXT

Text (StringOption) 3

DECIMAL

BigDecimal (DecimalOption)

DATE

Date (DateOption) 4

DATETIME

DateTime (DateTimeOption) 5

BOOLEAN

boolean (BooleanOption)

BYTE

byte (ByteOption)

SHORT

short (ShortOption)

3

org.apache.hadoop.io.Text , ...AsString は java.lang.String

4

com.asakusafw.runtime.value.Date [https://docs.asakusafw.com/0.10.3/release/api/com/asakusafw/runtime/value/Date.html]

5

com.asakusafw.runtime.value.DateTime [https://docs.asakusafw.com/0.10.3/release/api/com/asakusafw/runtime/value/DateTime.html]

プロパティ参照の対応付け

DMDLコンパイラは、それぞれのプロパティ参照に対して、次の名前の公開メソッドを作成します。

get<参照名>

また、上記メソッドの返戻値型は、リスト型のプロパティであれば java.util.List<プロパティの型>, マップ型のプロパティであれば java.util.Map<String, プロパティの型> となります。

なお、プロパティ参照を表すリストやマップは、以下の点においてJavaの標準と異なる点に注意が必要です。

プロパティの追加・削除などは不可能

List.set() や Map.put() などによって値を変更しようとした場合、引数に渡したオブジェクト そのものを格納せず 、オブジェクトのコピーを格納する

リストの並び替え (Collections.sort(), List.sort() など) は利用できない

データモデルの属性

データモデルに「属性」を定義しておくと、DMDLコンパイラが生成するプログラムを拡張できます。

データモデルの説明

データモデルのドキュメンテーションを変更するには、データモデルの定義の直前に "<データモデルの説明>" を付与します。

"サンプルのデータモデル"
example = { ... };

データモデルの説明は、レコードモデルだけでなく全てのモデルで指定できます。

データモデルの説明が指定されない場合、データモデルの名前で代用します。

プロパティの説明

プロパティのドキュメンテーションを変更するには、プロパティ定義やマッピングの直前に "<プロパティの説明>" を付与します。

order = {
    "商品コード"
    item_code : LONG;
    "商品価格"
    price : DECIMAL;
};
summarized order_summary = order => {
    "グループ化した商品コード"
    any item_code -> code;
    "商品価格の合計"
    sum price -> total;
} % code;

プロパティの説明が指定されない場合、プロパティの名前で代用します。

データモデルの名前空間

生成するプログラムのパッケージ名を(一部)変更するには、データモデル定義の直前に @namespace(value = <パッケージ名>) を指定します。

このパッケージ名は、データモデルの名前と同様に snake_case の形式で記述します ( 名前の形式 を参照 )。また、 . で区切って深い階層の名前も指定できます。

"名前空間付きのモデル"
@namespace(value = your.namespace)
example = { ... };

Attention

@namespace(value = "ex.a") ではなく @namespace(value = ex.a) のように直接指定します。

Tip

データモデルの説明と名前空間を同時に指定する場合、データモデルの説明を先に書きます。

データモデルの名前空間が指定されない場合、 dmdl という名前空間を利用します。

自動射影

利用可能なすべての射影をデータモデルに登録させるには、データモデル定義の直前に @auto_projection を指定します。

射影モデルが持つプロパティをすべて持つモデルに @auto_projection 属性を指定した場合、そのデータモデルには対象の射影が自動的に登録されます。

projective foo = {
    value1 : INT;
    value2 : LONG;
};
@auto_projection
bar = {
    value1 : INT;
    value2 : LONG;
    value3 : DOUBLE;
};

上記のように記述した場合、 bar には自動的に foo が射影として登録されます。

通常の場合、データモデルに登録される射影は、レコードモデルや射影モデルのプロパティ定義に直接指定された射影モデルのみです。現在のところ、結合モデルや集計モデルに射影を登録するには、この自動射影を利用する方法のみが提供されています。

プロパティ参照の詳細

プロパティ参照の型を指定する

プロパティ参照の定義を行う際に、それらの型を明示的に指定することもできます（通常は、要素のプロパティから自動的に推論します）。

プロパティ参照の名前と = の間に、リスト型であれば {<参照先の型>}, マップ型であれば {:<参照先の型>} の形式で指定します。

m = {
    a : INT;
    b : INT;
    c : INT;
    ref_list : {INT} = {a, b, c};
    ref_alist : {:INT} = { "A" : a, "B" : b, "C" : c, };
};

なお、要素を持たないプロパティ参照を定義する場合、明示的な型の指定が必須になります。

m = {
    ref_list : {INT} = {};
    ref_alist : {:TEXT} = {:};
};

プロパティ参照のスタブを定義する

射影モデル内にプロパティ参照を定義する場合、明示的な参照先のプロパティを省略した「スタブ」を定義することが可能です。

projective something = {

    // INTの参照リスト
    ref_list : {INT};

    // TEXTの参照マップ
    ref_alist : {:TEXT};
};

プロパティ参照のスタブを持つ射影を合成したモデルにおいては、スタブと同じ名前、同じ型の参照を明示的に定義する必要があります。

プロパティ参照の合成

データモデルの合成元にプロパティ参照が含まれる場合、合成先にはそのプロパティ参照が引き継がれます。

p0 = {
    a : INT;
    ref = {a};
};

// ref = {a} が引き継がれる
model = p0;

複数のデータモデルを合成する際に同一のプロパティ参照が複数含まれている場合、スタブでないプロパティ参照が2つ以上存在すると曖昧となりエラーになります（または、すべてがスタブの場合もエラーになります）。この場合、合成先のモデルでプロパティ参照を定義し直す必要があります。

p0 = {
    a : INT;
    ref = {a};
};

p1 = {
    b : INT;
    ref = {b};
};

m = p0 + p1 + {
    ref = {a, b};
};

または、特殊な記法として <参照名> = <データモデル名>.<参照名>; と記述することで、合成元の参照を明示的に指定できます。

p0 = {
    a : INT;
    ref = {a};
};

p1 = {
    a : INT;
    ref = {a};
};

m = p0 + p1 + {
    ref = p0.ref;
};

いずれの場合においても、合成元のすべての参照と、合成左記の参照が同じ型（リスト/マップ、要素の型）でなければなりません。

DMDLコンパイラプラグインの利用

DMDLコンパイラはプラグインの仕組みを備えており、DMDLの解析やデータモデルプログラムの生成などをある程度制御できるようになっています。

プラグインを利用するには、DMDLコンパイラの起動オプション -plugin にプラグインのJARファイルを指定します。

組み込みプラグイン

DMDLコンパイラには、標準で様々なプラグインが組み込まれています。以下は、主な組み込みプラグインの一覧です。

データモデルの名前空間 を指定する

自動射影 を行う

Writable インターフェースを実装する

TEXT 型のプロパティに ...AsString のメソッドを提供する

hashCode, equals, toString などの標準的なメソッドを実装

これらは、DMDLコンパイラの起動オプションを指定しなくても自動的に適用されます。

Direct I/Oとの連携

Direct I/Oと連携したバッチアプリケーションでは、Direct I/Oが提供する特別な データモデルの属性 を利用可能です。

詳しくは データの直接入出力 - Direct I/O を参照してください。

WindGateとの連携

WindGateと連携したバッチアプリケーションでは、WindGateが提供する特別な データモデルの属性 を利用可能です。

詳しくは 外部システムとの連携 - WindGate を参照してください。

DMDLコンパイラプラグインの開発

詳しくは DMDL開発者ガイド を参照して下さい。

DMDL開発者ガイド

この文書では、DMDLおよびDMDLコンパイラの拡張方法について紹介します。

Todo

DMDL > Developer Guide

アプリケーションの実装 - Asakusa DSL

Asakusa Frameworkでアプリケーションを作成するには、 Asakusa DSLで処理の流れや処理の本体を記述します。

DSLの構成

Asakusa DSLは3種類のDSLで構成されています。

Operator DSL

Operator DSLは「演算子」と呼ばれるデータフロー処理の最小単位を記述するDSLです。それぞれの演算子では単一のデータを表す「レコード」や、それらをグループ化した「グループ」に対する処理をJavaのプログラムとして記述できます。

Flow DSL

Flow DSLは演算子を組み合わせてデータフローの構造を記述するDSLです。このDSLではデータフローの構造を非循環有向グラフ (Directed Acyclic Graph: DAG)を構造の通りにそのまま記述できます。

Batch DSL

Batch DSLはデータフローを組み合わせて複雑なバッチ処理の流れを記述するDSLです。それぞれのデータフローを処理する順序を、依存関係のグラフ構造で記述できます。

関連するドキュメント

Asakusa DSLスタートガイド

Asakusa DSLユーザーガイド

演算子リファレンス

多相データフロー

ビューAPI

Asakusa DSL開発者ガイド

Asakusa DSLスタートガイド

この文書では Asakusa Framework スタートガイド の構成で、Asakusa DSLを使ってバッチアプリケーションを記述する方法について簡単に紹介します。

See also

Asakusa DSLのより詳しい情報は Asakusa DSLユーザーガイド を参照して下さい。

データモデルクラスを作成する

Asakusa DSLで取り扱う処理対象のデータモデルは、特定の形式で定義されたJavaのクラスで表されます。

これらのクラスを作成する方法は、 DMDLスタートガイド を参照して下さい。

演算子を記述する

Asakusa Frameworkでは、HadoopやSparkなどのフレームワークを直接利用する代わりに、「演算子」と呼ばれる処理の単位をデータフローの形式で組み合わせて処理を記述します。ここでは、その演算子を作成する方法を紹介します。

演算子の種類

演算子を作成するには「演算子の種類」を一つ選んで、その種類の制約の中でプログラムを作成することになります。以下は、Asakusa Frameworkで利用可能な演算子の種類の抜粋です。

演算子の種類 (抜粋)

名前

注釈型

概要

分岐演算子

Branch

レコードを内容に応じた出力に振り分ける

更新演算子

Update

レコードの内容を更新して出力する

変換演算子

Convert

レコードを別の種類のレコードに変換して出力する

マスタ結合演算子

MasterJoin

レコードにマスタデータを結合して出力する

マスタ分岐演算子

MasterBranch

レコードとマスタデータの内容に応じた出力に振り分ける

マスタつき更新演算子

MasterJoinUpdate

レコードの内容をマスタデータの情報を元に更新して出力する

単純集計演算子

Summarize

グループ化したレコードを集計して出力する

グループ結合演算子

CoGroup

複数種類のレコードをグループ化して任意の処理を行う

なお、上記の「注釈型」はOperator DSLで演算子のプログラムを記述する際に、プログラムに対して付与しなければならない演算子注釈の型を表しています。これらの注釈は、いずれも com.asakusafw.vocabulary.operator パッケージ 1 に宣言されています。

See also

利用可能な全ての演算子については、 演算子リファレンス を参照して下さい。

1

com.asakusafw.vocabulary.operator.package-summary [https://docs.asakusafw.com/0.10.3/release/api/com/asakusafw/vocabulary/operator/package-summary.html]

演算子クラスを作成する

それぞれの演算子は、演算子注釈を指定したJavaのメソッドとして宣言します。ここではまず、演算子を作成するためのクラスを宣言します。このクラスは、以下のようにJavaの抽象 ( abstract ) クラスとして宣言します 2 。

package com.example.operator;

public abstract class ExampleOperator {
    ...
}

なお、それぞれの演算子クラスは、末尾の名前が operator であるようなパッケージに配置することを推奨しています。

2

その他、publicなトップレベルクラスであり、型引数を宣言しない、明示的な親クラスや親インターフェースを指定しない、明示的なコンストラクタを宣言しない、などの制約があります。

演算子メソッドの作成

演算子クラスには、演算子注釈を指定したJavaのメソッドを宣言します。 Asakusa Frameworkが提供する全ての演算子注釈は、パッケージ com.asakusafw.vocabulary.operator 1 以下に配置されています。

演算子の種類によって演算子メソッドの構成は変わります。たとえば、メソッドを抽象メソッドとして宣言して、コンパイラが実装コードを自動的に生成するものなどもあります。全ての演算子メソッドで共通のルールは、以下の通りです。

全ての演算子メソッドは public で宣言する

メソッド1つに付き、演算子注釈は1つまで

同じ名前の演算子メソッドは同じクラスに宣言できない 3

See also

それぞれの演算子について詳しくは、 演算子リファレンス か、演算子注釈のドキュメンテーションコメントを参照して下さい。

3

演算子クラス内では、メソッドのオーバーロードを禁止しています

演算子メソッドの制限

ここで作成した演算子メソッドは、最終的にHadoopやSparkなどのプラットフォーム上で動作するプログラムの一部として利用されます。そのため、以下のようなプログラムを演算子メソッドの本体に書いた場合、期待した通りに動作しない場合があります。

フィールドの値を演算子間で共有する

ローカルシステムのファイルなどのリソースを利用する

スレッドを生成する

基本的には、演算子メソッドのフィールドに渡されたリソースや、その演算子メソッドのみから利用するフィールドを利用してプログラムを作成して下さい。

フレームワークAPI

Asakusa Frameworkは、演算子メソッドを記述する際にいくつか便利なAPIを用意しています。演算子の中では前項のようにできることに制限がありますが、フレームワークAPIを併用することでその制限のいくつかを緩和できる可能性があります。

フレームワークAPIにはレポートとバッチ設定情報の2種類がコアAPIとして用意されています。

See also

フレームワークAPIの利用方法については Asakusa DSLユーザーガイド を参照して下さい。

演算子の実装例

いくつかの演算子について、実装例を示します。ここでの実装例は1クラス1演算子メソッドとなっていますが、実際には1つのクラスに複数の演算子メソッドを宣言することも可能です。

更新演算子の実装例

更新演算子は、 Update 注釈を付与したメソッドを宣言します。以下は、 Hoge クラスのデータモデルオブジェクトのプロパティ value を 100 に変更するような、更新演算子の例です。

public abstract class ExampleOperator {

    /**
     * レコードの値に100を設定する。
     * @param hoge 更新するレコード
     */
    @Update
    public void edit(Hoge hoge) {
        hoge.setValue(100);
    }
    ...
}

マスタ結合演算子の実装例

マスタ結合演算子は、 MasterJoin 注釈を付与したメソッドを宣言します。以下は、 HogeTrn のデータモデルオブジェクトに、マスタである HogeMst を結合するような、マスタ結合演算子の例です。

public abstract class ExampleOperator {

    /**
     * レコードHogeMstとHogeTrnを結合し、結合結果のHogeを返す。
     * @param master マスタデータ
     * @param tx トランザクションデータ
     * @return 結合結果
     */
    @MasterJoin
    public abstract Hoge join(HogeMst master, HogeTrn tx);

    ...
}

マスタ結合演算子は、結合条件や結合方法をデータモデルクラスから自動的に推定して、適切なコードを自動生成します。そのため、抽象( abstract )メソッドとして宣言し、戻り値は結合モデルでなければなりません。

See also

結合モデルについては DMDLユーザーガイド を参照してください。

非等価結合を用いるマスタつき更新演算子の実装例

マスタつき更新演算子は、 MasterJoinUpdate 注釈を付与したメソッドを宣言します。また、非等価結合を含む場合には、さらに補助演算子として MasterSelection 注釈を付与したメソッドを宣言し、 MasterJoinUpdate 注釈からそのメソッドを指定して下さい。以下は、 HogeTrn のデータモデルオブジェクトに、マスタである ItemMst の項目を一部追記するような、マスタつき更新演算子の例です。

public abstract class ExampleOperator {

    /**
     * マスタの価格をトランザクションデータに設定する。
     * @param master マスタデータ
     * @param tx 変更するトランザクションデータ
     */
    @MasterJoinUpdate(selection = "selectItemMst")
    public void updateWithMaster(
            @Key(group = "id") ItemMst master,
            @Key(group = "itemId") HogeTrn tx) {
        tx.setPrice(master.getPrice());
    }

    /**
     * 有効なマスタを選択する。
     * @param masters 選択対象のマスタデータ一覧
     * @param tx トランザクションデータ
     * @return 実際に利用するマスタデータ、利用可能なものがない場合はnull
     */
    @MasterSelection
    public ItemMst selectItemMst(List<ItemMst> masters, HogeTrn tx) {
        for (ItemMst mst : masters) {
            if (mst.getStart() <= tx.getDate() &&
                    tx.getDate() <= mst.getEnd()) {
                return mst;
            }
        }
        return null;
    }
}

マスタつき更新演算子は、結合条件をメソッドの引数に対する Key 注釈で記述します。このとき、要素 group に指定する値は、等価結合に用いるプロパティの名前です。同時に、非等価結合の部分を selectItemMst メソッドに記述して、 MasterJoinUpdate 注釈の要素 selection から指定しています。

単純集計演算子の実装例

単純集計演算子は、 Summarize 注釈を付与した抽象メソッドを宣言します。以下は、 Hoge クラスのデータモデルオブジェクトを集計し、 HogeTotal クラスのデータモデルオブジェクトに格納する例です。

public abstract class ExampleOperator {

    /**
     * レコードHogeをHogeTotalに集計する。
     * @param hoge 集計対象
     * @return 集計結果
     */
    @Summarize
    public abstract HogeTotal summarize(Hoge hoge);

    ...
}

なお、この演算子は集計モデルである HogeTotal を作成した際の情報を元に、自動的に Hoge を集計するプログラムを生成します。そのため、抽象( abstract )メソッドとして宣言し、戻り値は必ず集計モデルでなければなりません。

See also

集計モデルについては DMDLユーザーガイド を参照してください。

グループ整列演算子の実装例

グループ整列演算子は、 GroupSort 注釈を付与したメソッドを宣言します。以下は、 Hoge クラスのデータモデルオブジェクトをプロパティ name でグループ化し、さらにプロパティ age の昇順で並べたリストを引数に受け取ったのちに、そのリストの先頭と末尾の要素をそれぞれ別の出力 first, last に渡すような例です。

public abstract class ExampleOperator {

    /**
     * レコードHogeを名前ごとに年齢の若い順に並べ、先頭と末尾だけをそれぞれ結果に流す。
     * @param hogeList グループごとのリスト
     * @param first グループごとの先頭要素
     * @param last グループごとの末尾要素
     */
    @GroupSort
    public void firstLast(
            @Key(group = "name", order = "age ASC") List<Hoge> hogeList,
            Result<Hoge> first,
            Result<Hoge> last) {
        first.add(hogeList.get(0));
        last.add(hogeList.get(hogeList.size() - 1));
    }
    ...
}

メソッドの引数に指定している Result は、この演算子の出力を表しています。また、注釈 Key の要素 order は、要素の整列順序を表しています。

分岐演算子の実装例

更新演算子は、 Branch 注釈を付与したメソッドを宣言します。以下は、 Hoge クラスのデータモデルオブジェクトのプロパティ value の値に応じてそれぞれの出力にレコードを振り分けるような例です。

public abstract class ExampleOperator {

    /**
     * レコードの状態ごとに処理を分岐する。
     * @param hoge 対象のレコード
     * @return 分岐先を表すオブジェクト
     */
    @Branch
    public Status select(Hoge hoge) {
        int value = hoge.getPrice();
        if (value <= 100) {
            return Status.OK;
        }
        else {
            return Status.NG;
        }
    }

    /**
     * レコードの状態。
     */
    public enum Status {
        /**
         * 成功。
         */
        OK,

        /**
         * 失敗。
         */
        NG,
    }
    ....
}

分岐演算子は出力先を示した列挙型と組み合わせて使用します。個々のレコードに対して条件判定を行い、分岐先の出力先を示す列挙型を戻り値として返します。

演算子のテスト

演算子のテストは、通常のJavaメソッドをテストする方法でテストして下さい。

より詳しくは、 アプリケーションテストスタートガイド を参照して下さい。

なお、フレームワークAPIを利用したメソッドをテストする場合、フレームワークAPIをモックに差し替えてテストすることも可能です。

演算子のビルド

Asakusa Framework スタートガイド の流れで作成したEclipseプロジェクト上では、通常のJavaを使った開発と同様、ソースを記述するとインクリメンタルビルドによって演算子のコンパイルが自動的に行われるほか、注釈プロセッサによって演算子用のJavaソースが以下のディレクトリに自動生成されます。

<プロジェクトのルート>/build/generated-sources/annotations

または、Gradleを利用してJavaコンパイラを実行すると、注釈プロセッサを起動できます。これはGradleの compileJava タスクで起動するので、プロジェクト内で以下のようにコマンドを実行します。

./gradlew compileJava

その他、 assemble タスクや build タスクなどでも自動的に注釈プロセッサが起動します。

注釈プロセッサによって、演算子を組み合わせてフローを構築するためのファクトリークラス(演算子ファクトリクラス)と、演算子クラスの実装を提供する実装クラスの2つが自動的に生成されます。そのとき、演算子ファクトリクラスは、元の演算子クラスの末尾に Factory を付与した名前のクラスで、実装クラスは同様に Impl を付与した名前のクラスとなります。

データフローを記述する

データフローは、演算子を組み合わせて一連のデータ処理の流れを記述したものです。 Asakusa DSLでは、外部入力をソースにデータを処理して外部出力に結果を書き戻す「ジョブフロー」と、演算子を組み合わせてより大きな演算子を構築する「フロー部品」を、それぞれ定義できます。

この章では、前者のジョブフローのみを紹介します。フロー部品については Asakusa DSLユーザーガイド を参照して下さい。

外部入出力を定義する

ジョブフローが利用する外部入出力を定義するには、それぞれ「インポーター」と「エクスポーター」の処理内容を記述します。

Asakusa Frameworkでは以下の外部入出力を提供しています。

Direct I/O を利用してHadoopから参照可能なデータソースを直接入出力に利用する

WindGate と連携してローカルファイルシステムやリレーショナルデータベースのテーブル情報を入出力に利用する

以降では、サンプルとしてWindGateを利用して、ローカルファイルシステム上のCSVファイルを外部入出力に利用します。

CSVフォーマットを定義する

WindGateがローカルファイルシステム上のCSVファイルを読み書きできるように、それぞれのデータモデルに対するCSVフォーマットを定義します。

データモデルクラスを作成する 作成したデータモデルの手前に、次のように @windgate.csv という属性をつけてください。この作業により、対象のデータモデルと同じ形式のCSVファイルをWindGateが入出力に利用できるようになります。

@windgate.csv
example_model = {
    ...
};

この属性をつけるのは、CSVの入出力に利用するデータモデルのみで十分です。この属性をつけた状態でデータモデルを再作成すると、元のデータモデルクラスのほかに以下の3つのクラスが作成されます。

<パッケージ名>.csv.<データモデル名>CsvSupport

<パッケージ名>.csv.Abstract<データモデル名>ImporterDescription

<パッケージ名>.csv.Abstract<データモデル名>ExporterDescription

CSVフォーマットについては、 WindGateユーザーガイド も参考にしてください。

WindGateからインポートする

WindGateからデータをインポートしてジョブフローで処理するには、 FsImporterDescription 4 や JdbcImporterDescription 5 など、 WindGateImporterDescription 6 のサブクラスを継承したクラスを作成し、必要なメソッドを実装します。

CSVフォーマットを定義する で生成された Abstract<データモデル名>ImporterDescription はそれらの骨格実装を行ったクラスで、このクラスを継承して以下のメソッドをオーバーライドするだけでインポート処理を記述できます。

String getProfileName()

インポータが使用するプロファイル名を戻り値に指定します。

インポータは実行時に $ASAKUSA_HOME/windgate/profile 以下の <プロファイル名>.properties に記述された設定を元に動作します。今回はデフォルトの "asakusa" という文字列を return 文に指定してください。

String getPath()

インポートするCSVファイルのパスを指定します。

DataSize getDataSize()

このインポータが取り込むデータサイズの分類を指定します。

以下は Document というデータモデルを宣言した場合の実装例です。

public class DocumentFromCsv extends AbstractDocumentCsvImporterDescription {

    @Override
    public String getProfileName() {
        return "asakusa";
    }

    @Override
    public String getPath() {
        return "input.csv";
    }
}

4

com.asakusafw.vocabulary.windgate.FsImporterDescription [https://docs.asakusafw.com/0.10.3/release/api/com/asakusafw/vocabulary/windgate/FsImporterDescription.html]

5

com.asakusafw.vocabulary.windgate.JdbcImporterDescription [https://docs.asakusafw.com/0.10.3/release/api/com/asakusafw/vocabulary/windgate/JdbcImporterDescription.html]

6

com.asakusafw.vocabulary.windgate.WindGateImporterDescription [https://docs.asakusafw.com/0.10.3/release/api/com/asakusafw/vocabulary/windgate/WindGateImporterDescription.html]

WindGateにエクスポートする

ジョブフローの処理結果をHadoopファイルシステムに書き出すには、 FsExporterDescription 7 や JdbcExporterDescription 8 など、 WindGateExporterDescription 9 のサブクラスを継承したクラスを作成し、必要なメソッドを実装します。

「 CSVフォーマットを定義する 」で生成された Abstract<データモデル名>ExporterDescription はそれらの骨格実装を行ったクラスで、このクラスを継承して以下のメソッドをオーバーライドするだけでインポート処理を記述できます。

String getProfileName()

エクスポータが使用するプロファイル名を戻り値に指定します。

インポータと同様に "asakusa" という文字列を return 文に指定してください。

String getPath()

エクスポートするCSVファイルのパスを指定します。

以下は Document というデータモデルを宣言した場合の実装例です。

public class DocumentToCsv extends AbstractDocumentCsvExporterDescription {

    @Override
    public String getProfileName() {
        return "asakusa";
    }

    @Override
    public String getPath() {
        return "output.csv";
    }
}

7

com.asakusafw.vocabulary.windgate.FsExporterDescription [https://docs.asakusafw.com/0.10.3/release/api/com/asakusafw/vocabulary/windgate/FsExporterDescription.html]

8

com.asakusafw.vocabulary.windgate.JdbcExporterDescription [https://docs.asakusafw.com/0.10.3/release/api/com/asakusafw/vocabulary/windgate/JdbcExporterDescription.html]

9

com.asakusafw.vocabulary.windgate.WindGateExporterDescription [https://docs.asakusafw.com/0.10.3/release/api/com/asakusafw/vocabulary/windgate/WindGateExporterDescription.html]

Direct I/Oを利用する

Direct I/Oを利用してHadoopが管理するデータソースを入出力に利用する方法は、 Direct I/O ユーザーガイド を参照してください。

WindGateと連携する

WindGateはCSVのほか、さまざまな形式のファイルやデータベースと連携できます。詳しくは WindGateユーザーガイド を参照してください。

ジョブフロークラスの作成

それぞれのジョブフローは、 FlowDescription 10 を継承したJavaのクラス(ジョブフロークラス)として宣言します 11 。さらにジョブフローであることを表すために、クラスの注釈として JobFlow 12 を指定し、要素 name にこのジョブフローの名前を指定します。

package com.example.jobflow;

import com.asakusafw.vocabulary.flow.*;

@JobFlow(name = "example")
public class ExampleJobFlow extends FlowDescription {
    ...
}

なお、それぞれのジョブフロークラスは、末尾の名前が jobflow であるようなパッケージに配置することを推奨しています。

10

com.asakusafw.vocabulary.flow.FlowDescription [https://docs.asakusafw.com/0.10.3/release/api/com/asakusafw/vocabulary/flow/FlowDescription.html]

11

その他、publicなトップレベルクラスであり、具象クラスである( abstract を指定しない)、型引数を宣言しない、 FlowDescription 以外の親クラスや親インターフェースを指定しない、などの制約があります。

12

com.asakusafw.vocabulary.flow.JobFlow [https://docs.asakusafw.com/0.10.3/release/api/com/asakusafw/vocabulary/flow/JobFlow.html]

コンストラクタの作成

ジョブフローの入出力は、ジョブフロークラスのコンストラクタで宣言します。このコンストラクタは public コンストラクタとして宣言し、次のような型の仮引数を宣言します。

ジョブフローへの入力を表す In<T> 13

型引数には入力されるデータモデルクラスの型を指定する

インポート処理記述を注釈 Import 14 で指定する

ジョブフローからの出力を表す Out<T> 15

型引数には出力するデータモデルクラスの型を指定する

エクスポート処理記述を注釈 Export 16 で指定する

なお、注釈 Import および Export には、それぞれ名前とインポータやエクスポータの処理内容を記述したクラスを指定します。ここで指定した処理内容に応じて、ジョブフローの入力や出力の方法が決まります。

以下のように、コンストラクタの引数と同名のインスタンスフィールドを作成し、コンストラクタの引数をフィールドに代入するとよいでしょう。

package com.example.jobflow;

import com.asakusafw.vocabulary.flow.*;

@JobFlow(name = "example")
public class ExampleJobFlow extends FlowDescription {

    In<Hoge> in;
    Out<Hoge> out;

    public ExampleJobFlow(
            @Import(name = "hoge", description = HogeFromCsv.class)
            In<Hoge> in,
            @Export(name = "hoge", description = HogeIntoCsv.class)
            Out<Hoge> out) {
        this.in = in;
        this.out = out;
    }
    ...
}

13

com.asakusafw.vocabulary.flow.In [https://docs.asakusafw.com/0.10.3/release/api/com/asakusafw/vocabulary/flow/In.html]

14

com.asakusafw.vocabulary.flow.Import [https://docs.asakusafw.com/0.10.3/release/api/com/asakusafw/vocabulary/flow/Import.html]

15

com.asakusafw.vocabulary.flow.Out [https://docs.asakusafw.com/0.10.3/release/api/com/asakusafw/vocabulary/flow/Out.html]

16

com.asakusafw.vocabulary.flow.Export [https://docs.asakusafw.com/0.10.3/release/api/com/asakusafw/vocabulary/flow/Export.html]

ジョブフローメソッドの作成

ジョブフローの内容は、 FlowDescription クラスの describe メソッドをオーバーライドして記述します。このメソッドの中には、コンストラクタに指定した入出力と作成した演算子を接続して、データフローを構築するようなプログラムを書きます。

...
@JobFlow(name = "example")
public class ExampleJobFlow extends FlowDescription {
    ...
    @Override
    public void describe() {
        // ここにデータフローを記述する
    }
}

演算子ファクトリを用意する

データフローを構築するには、まず演算子のビルド結果として生成された演算子ファクトリをインスタンス化します。

演算子ファクトリには、元となった演算子メソッドと同じ名前のメソッドがそれぞれ定義されています。これはデータフロー中の演算子を新たに作成するファクトリメソッドで、対応する演算子を組み立てるために利用します。

また、Asakusa Frameworkは CoreOperatorFactory 17 という組み込みの演算子ファクトリも提供しています。以下はそれぞれの演算子ファクトリをインスタンス化する例です。

@Override
public void describe() {
    CoreOperatorFactory core = new CoreOperatorFactory();
    ExampleOperatorFactory example = new ExampleOperatorFactory();
    ...
}

17

com.asakusafw.vocabulary.flow.util.CoreOperatorFactory [https://docs.asakusafw.com/0.10.3/release/api/com/asakusafw/vocabulary/flow/util/CoreOperatorFactory.html]

入力と演算子を接続する

コンストラクタに指定した In オブジェクトを、演算子ファクトリのメソッドの引数に渡すと、ジョブフローに入力されたデータを、その演算子で処理することができます。このとき、入力されるデータの種類と、演算子に入力できるデータの種類は一致していなければなりません。

以下は、データモデル Hoge に対して更新演算子として定義した演算子メソッド edit を実行する例です。

In<Hoge> in;

@Override
public void describe() {
    ExampleOperatorFactory example = new ExampleOperatorFactory();
    Edit edit = example.edit(in);
}

演算子と演算子を接続する

演算子ファクトリの各メソッドが返すオブジェクトは、それぞれ対応する演算子を表しています。このオブジェクトはそれぞれいくつかの公開フィールドを持っていて、演算子の出力を表しています。

演算子の出力を別の演算子の入力に接続することで、複雑なデータの流れを表現できます。

以下は、上記例で演算子メソッド edit を実行したデータモデル Hoge にして、分岐演算子として定義した演算子メソッド select を実行する例です。

In<Hoge> in;

@Override
public void describe() {
    ExampleOperatorFactory example = new ExampleOperatorFactory();
    Edit edit = example.edit(in);
    Select select = example.select(edit.out);
}

演算子と出力を接続する

ジョブフローの結果を出力する際には、コンストラクタに指定された Out オブジェクトの add() メソッドの引数に、それぞれの演算子の出力を渡します。こうすることで、その演算子の出力結果がそのままジョブフローの出力結果となります。このとき、両者の出力は同じデータの種類でなければなりません。

なお、それぞれの演算子の出力は、いずれかの演算子への入力、またはジョブフローからの出力と接続されている必要があります。不要な演算子の出力がある場合、停止演算子（ CoreOperatorFactory.stop() メソッド）を利用してその出力を利用しないことを明示的にコンパイラに指示する必要があります。

以下の例では、上記例で演算子メソッド select を実行したデータモデル Hoge にして、分岐先の出力 ok をジョブフローの出力結果として出力しています。また、分岐先の出力 ng は出力せず、ジョブフロー内でデータを破棄しています。

In<Hoge> in;
In<Hoge> out;

@Override
public void describe() {
    CoreOperatorFactory core = new CoreOperatorFactory();
    ExampleOperatorFactory example = new ExampleOperatorFactory();
    Edit edit = example.edit(in);
    Select select = example.select(edit.out);
    out.add(select.ok);
    core.stop(select.ng);
}

ジョブフローの実装例

ジョブフローの実装例を示します。

この実装例では、これまでの説明と同様にWindGateを利用してCSVデータを読み書きします。ここで紹介する例の完全なコードは、サンプルプログラム集 18 に含まれるプロジェクト example-windgate-csv を参照してください。

18

https://github.com/asakusafw/asakusafw-examples

インポート処理の実装例

example-windgate-csv のバッチ処理では、以下の3種類のデータをインポートしています。

店舗情報マスタ ( StoreInfoFromCsv )

商品情報マスタ ( ItemInfoFromCsv )

売上明細データ ( SalesDetailFromCsv )

まず、店舗情報のマスタデータである <ベースディレクトリ>/master/store_info.csv にあるCSVファイルを読み出す例 ( StoreInfoFromCsv ) を以下に示します。この <ベースディレクトリ> の部分はWindGateの設定で、既定では /tmp/windgate-<ログインユーザー名> を利用します。

package com.asakusafw.example.csv.jobflow;

import com.asakusafw.example.csv.modelgen.dmdl.csv.AbstractStoreInfoCsvImporterDescription;

public class StoreInfoFromCsv extends AbstractStoreInfoCsvImporterDescription {

    @Override
    public String getProfileName() {
        return "asakusa";
    }

    @Override
    public String getPath() {
        return "master/store_info.csv";
    }

    @Override
    public DataSize getDataSize() {
        return DataSize.TINY;
    }
}

WindGateからインポートする 際の手順に従い、自動生成されたクラスを継承して必要なメソッドを実装しています。

このとき、 getDataSize() メソッドは DataSize.TINY という値を返しています。 .../store_info.csv は店舗情報のマスタデータを表すもので、それほど大きくないという前提です。

Hint

データサイズに DataSize.TINY を指定することで、いくつかの最適化が有効になります。詳しくは Asakusa DSLユーザーガイド を参照してください。

次に、商品情報のマスタデータとして <ベースディレクトリ>/master/item_info.csv にあるCSVファイルを読み出す例 ( ItemInfoFromCsv ) です。

package com.asakusafw.example.csv.jobflow;

import com.asakusafw.example.csv.modelgen.dmdl.csv.AbstractItemInfoCsvImporterDescription;

public class ItemInfoFromCsv extends AbstractItemInfoCsvImporterDescription {

    @Override
    public String getProfileName() {
        return "asakusa";
    }

    @Override
    public String getPath() {
        return "master/item_info.csv";
    }

    @Override
    public DataSize getDataSize() {
        return DataSize.LARGE;
    }
}

先ほどの例と異なり、 getDataSize() メソッドは DataSize.LARGE という値を返しています。

さらに、売上明細データとして <ベースディレクトリ>/sales/<日付>.csv にあるCSVファイルを読み出す例 ( SalesDetailFromCsv ) です。 <日付> の部分はバッチ処理を開始する際に date という名前の引数で指定できるようにしています。

package com.asakusafw.example.csv.jobflow;

import com.asakusafw.example.csv.modelgen.dmdl.csv.AbstractSalesDetailCsvImporterDescription;

public class SalesDetailFromCsv extends AbstractSalesDetailCsvImporterDescription {

    @Override
    public String getProfileName() {
        return "asakusa";
    }

    @Override
    public String getPath() {
        return "sales/${date}.csv";
    }

    @Override
    public DataSize getDataSize() {
        return DataSize.LARGE;
    }
}

エクスポート処理の実装例

インポート処理の実装例 と同様に、エクスポート処理の部分の実装例を紹介します。

example-windgate-csv のバッチ処理では、以下の2種類のデータをエクスポートしています。

カテゴリ別売上集計 ( CategorySummaryToCsv )

エラー情報 ( ErrorRecordToCsv )

カテゴリ別売上集計を <ベースディレクトリ>/result/category-<日付>.csv にCSV形式で書き出す例 ( CategorySummaryToCsv ) です。 <日付> の部分は売上明細データをインポートする際と同様に、バッチ処理を開始する際の date で指定された文字列を利用します。

package com.asakusafw.example.csv.jobflow;

import com.asakusafw.example.csv.modelgen.dmdl.csv.AbstractCategorySummaryCsvExporterDescription;

public class CategorySummaryToCsv extends AbstractCategorySummaryCsvExporterDescription {

    @Override
    public String getProfileName() {
        return "asakusa";
    }

    @Override
    public String getPath() {
        return "result/category-${date}.csv";
    }
}

上記は、 WindGateにエクスポートする 際の手順に従い、自動生成されたクラスを継承して必要なメソッドを実装しています。

エラー情報もカテゴリ別売上集計と同様の形で <ベースディレクトリ>/result/error-<日付>.csv にCSV形式で書き出します ( ErrorRecordToCsv )。

package com.asakusafw.example.csv.jobflow;

import com.asakusafw.example.csv.modelgen.dmdl.csv.AbstractErrorRecordCsvExporterDescription;

public class ErrorRecordToCsv extends AbstractErrorRecordCsvExporterDescription {

    @Override
    public String getProfileName() {
        return "asakusa";
    }

    @Override
    public String getPath() {
        return "result/error-${date}.csv";
    }
}

ジョブフロー本体の実装例

最後にジョブフローの例を示します。

package com.asakusafw.example.csv.jobflow;

import com.asakusafw.example.csv.modelgen.dmdl.model.*;
import com.asakusafw.example.csv.operator.CategorySummaryOperatorFactory;
import com.asakusafw.example.csv.operator.CategorySummaryOperatorFactory.*;
import com.asakusafw.vocabulary.flow.*;
import com.asakusafw.vocabulary.flow.util.*;

/**
 * カテゴリ別に売上の集計を計算する。
 */
@JobFlow(name = "byCategory")
public class CategorySummaryJob extends FlowDescription {

    final In<SalesDetail> salesDetail;

    final In<StoreInfo> storeInfo;

    final In<ItemInfo> itemInfo;

    final Out<CategorySummary> categorySummary;

    final Out<ErrorRecord> errorRecord;

    /**
     * ジョブフローインスタンスを生成する。
     * @param salesDetail 売上明細
     * @param storeInfo 店舗マスタ
     * @param itemInfo 商品マスタ
     * @param categorySummary カテゴリ別集計結果
     * @param errorRecord エラーレコード
     */
    public CategorySummaryJob(
            @Import(name = "salesDetail", description = SalesDetailFromCsv.class)
            In<SalesDetail> salesDetail,
            @Import(name = "storeInfo", description = StoreInfoFromCsv.class)
            In<StoreInfo> storeInfo,
            @Import(name = "itemInfo", description = ItemInfoFromCsv.class)
            In<ItemInfo> itemInfo,
            @Export(name = "categorySummary", description = CategorySummaryToCsv.class)
            Out<CategorySummary> categorySummary,
            @Export(name = "errorRecord", description = ErrorRecordToCsv.class)
            Out<ErrorRecord> errorRecord) {
        this.salesDetail = salesDetail;
        this.storeInfo = storeInfo;
        this.itemInfo = itemInfo;
        this.categorySummary = categorySummary;
        this.errorRecord = errorRecord;
    }

    @Override
    protected void describe() {
        CoreOperatorFactory core = new CoreOperatorFactory();
        CategorySummaryOperatorFactory operators = new CategorySummaryOperatorFactory();

        // 店舗コードが妥当かどうか調べる
        CheckStore checkStore = operators.checkStore(storeInfo, salesDetail);

        // 売上に商品情報を載せる
        JoinItemInfo joinItemInfo = operators.joinItemInfo(itemInfo, checkStore.found);

        // 売上をカテゴリ別に集計
        SummarizeByCategory summarize = operators.summarizeByCategory(joinItemInfo.joined);

        // 集計結果を出力
        categorySummary.add(summarize.out);

        // 存在しない店舗コードでの売上はエラー
        SetErrorMessage unknownStore = operators.setErrorMessage(
                core.restructure(checkStore.missed, ErrorRecord.class),
                "店舗不明");
        errorRecord.add(unknownStore.out);

        // 商品情報が存在しない売上はエラー
        SetErrorMessage unknownItem = operators.setErrorMessage(
                core.restructure(joinItemInfo.missed, ErrorRecord.class),
                "商品不明");
        errorRecord.add(unknownItem.out);
    }
}

ジョブフローのテスト

ジョブフローのテストは、Asakusa Frameworkが提供するテストドライバーを利用して行います。

詳しくは、 アプリケーションテストスタートガイド を参照して下さい。

バッチを記述する

バッチはこれまでに紹介したジョブフローをワークフローの形式で組み合わせて、一連の処理を実現するための構造です。

バッチクラスの作成

それぞれのバッチは、 BatchDescription 19 を継承したJavaのクラス(バッチクラス)として宣言します 20 。また、付加情報を表すために、クラスの注釈として Batch 21 を指定して要素 name にこのバッチの名前を指定します。

以下はバッチクラスを作成する例です。

package com.example.batch;

import com.asakusafw.vocabulary.batch.*;

@Batch(name = "example")
public class ExampleBatch extends BatchDescription {
    ...
}

なお、それぞれのバッチクラスは、末尾の名前が batch であるようなパッケージに配置することを推奨しています。

19

com.asakusafw.vocabulary.batch.BatchDescription [https://docs.asakusafw.com/0.10.3/release/api/com/asakusafw/vocabulary/batch/BatchDescription.html]

20

その他、publicなトップレベルクラスであり、具象クラスである( abstract を指定しない)、型引数を宣言しない、明示的な親クラスや親インターフェースを指定しない、明示的なコンストラクタを宣言しない、などの制約があります。

21

com.asakusafw.vocabulary.batch.Batch [https://docs.asakusafw.com/0.10.3/release/api/com/asakusafw/vocabulary/batch/Batch.html]

バッチメソッドの作成

バッチの内容は、 BatchDescription クラスの describe メソッドをオーバーライドして記述します。このメソッドの中には、ジョブフローの依存関係を記述して、バッチ全体を構築するようなプログラムを書きます。

以下はバッチメソッドを記述する例です。

@Batch(name = "example")
public class ExampleBatch extends BatchDescription {
    @Override
    public void describe() {
        Work first = run(FirstFlow.class).soon();
        Work second = run(SecondFlow.class).after(first);
        Work para = run(ParallelFlow.class).after(first);
        Work join = run(JoinFlow.class).after(second, para);
        ...
    }
}

バッチの内部で実行するジョブフローは、 BatchDescription クラスから継承した run() メソッドで指定します。同メソッドには対象のジョブフロークラスのクラスリテラルを指定し、そのままメソッドチェインで soon() や after() メソッドを起動します。

soon メソッドはバッチの内部で最初に実行されるジョブフローを表し、 after メソッドは依存関係にある処理を引数に指定して、それらの処理が全て完了後に実行されるジョブフローを表します。

バッチの実装例

バッチの単純な例を示します。ここで紹介する例の完全なコードも、サンプルプログラム集 22 に含まれるプロジェクト example-windgate-csv にあります。

以下の例は非常に簡単なバッチで、 TutorialJob というジョブフローを実行するのみです。また、バッチの名前には example.summarizeSales を指定しています。

package com.asakusafw.example.csv.batch;

import com.asakusafw.example.csv.jobflow.CategorySummaryJob;
import com.asakusafw.vocabulary.batch.Batch;
import com.asakusafw.vocabulary.batch.BatchDescription;

@Batch(name = "example.summarizeSales")
public class SummarizeBatch extends BatchDescription {

    @Override
    protected void describe() {
        run(CategorySummaryJob.class).soon();
    }
}

22

https://github.com/asakusafw/asakusafw-examples

バッチアプリケーションを生成する

Asakusa DSLからバッチアプリケーションを生成するには、 Gradle利用してAsakusa DSLコンパイラを実行します。

これはGradleの compileBatchapp タスクで起動するので、プロジェクト内で以下のようにコマンドを実行します。

./gradlew compileBatchapp

その他、 jarBatchapp タスクや assemble タスク、 build タスクなどでも自動的にコンパイラが起動します。

バッチアプリケーションの生成方法やGradleの利用方法については、 Asakusa Gradle Plugin ユーザーガイド などを参照してください。

バッチアプリケーションを実行する

作成したバッチアプリケーションの実行方法は、 YAESSスタートガイド などを参照してください。

Asakusa DSLユーザーガイド

この文書では、Asakusa DSLおよびDSLコンパイラの利用方法について紹介します。

DSLの概要

Asakusa DSLは次の3種類のDSLで構成されています。

Operator DSL

Javaでデータ操作の処理を「演算子」として記述する

Flow DSL

演算子を組み合わせて「データフロー」を記述する

Batch DSL

データフローを組み合わせて「業務バッチ」を記述する

アプリケーションの設計と実装

Asakusa DSLは、データフロー形式でのバッチ処理設計から素直な実装を作成できることを目標に設計しています。

データフローは大雑把にいえば、入力データをプロセスで加工して出力するという流れを取ります。 Flow DSL ではそのようなデータフローを直接記述でき、データを加工するプロセスは Operator DSL で通常のJavaを使って手続き的に記述できます。そのため、設計の段階からデータフローや処理の単位を意識することで、その設計内容をインプットとしてAsakusa DSLを用いた実装をスムーズに行うことができるようになります。

Asakusa Frameworkを利用したバッチ処理の設計例については、 Asakusa Frameworkコミュニティサイト [http://www.asakusafw.com/] の バッチ設計と実装ガイド [http://www.asakusafw.com/techinfo/methodology.html] を参照してください。

DSLコンパイラ

Asakusa DSLで記述したプログラムは、Asakusa Frameworkに付属のAsakusa DSLコンパイラを使ってHadoop(MapReduce)やSparkなどの各プラットフォーム（以下「実行プラットフォーム」）で実行可能なプログラムに変換します。

このコンパイラは2種類のコンパイラから構成されています。

Operator DSLコンパイラ

Operator DSL をコンパイルして、 Flow DSL で使える部品を生成するコンパイラ。 Javaの注釈プロセッサとして提供している。

Batch DSLコンパイラ

Batch DSL をコンパイルして、実行プラットフォーム向けのプログラムを生成するコンパイラ。コマンドラインインターフェースを提供している。

Batch DSLコンパイラは実行プラットフォームごとに対応するコンパイラを提供します。

なお、DSLが3層であるのに対し、コンパイラは2層のみに対応しています。直接のコンパイルを行わない Flow DSL についても、テスト時には単体でコンパイルして実行を行えるようになっています。

Operator DSL

Operator DSLは「 演算子 」と呼ばれるデータフロー処理の最小単位を記述するDSLです。それぞれの演算子では単一のデータを表す「レコード」や、それらをグループ化した「グループ」に対する処理をJavaのプログラムとして記述できます。

演算子

Asakusa DSLにおいて、演算子は「複数のデータセットを入力して加工し、複数のデータセットを出力するもの」といえます。この演算子を組み合わせて大きなデータフローを構築していくのが、このフレームワークでの標準的な設計開発手法です。

演算子には「種類」というものがあり、それぞれ入出力や処理の内容に制限を与えています。演算子リファレンス から演算子の種類を選択し、実際の処理内容を決めていきます。

それぞれの演算子は、Askausaが提供するOperator DSLを使って記述します。 DSLといっても難しいものではなく、通常のJavaのメソッド宣言に演算子用のメタデータを指定する形で記述できます。

このように演算子を定義するメソッドをAsakusaでは 演算子メソッド とよび、それらを宣言しているクラスを 演算子クラス と呼んでいます。

演算子クラス

演算子クラスは 演算子メソッド を定義するためのJavaのクラスです。基本的なJavaの 抽象クラス ですが、以下のような制約があります。

トップレベルクラスとして宣言する

public , abstract として宣言する

型引数を宣言しない

明示的な親クラスやインターフェースを指定しない

明示的なコンストラクタを宣言しない

演算子メソッド以外の public メソッドを宣言しない

上記に含まれない、たとえばフィールドの宣言などは自由に行えます。

以下は演算子クラスの例です。

package com.example.operator;

public abstract class ExampleOperator {
    ...
}

Hint

Asakusa Framework 0.10.0 より、演算子クラスに abstract を指定するのは必須ではなくなりました。ただし、演算子メソッドに abstract を指定するには、クラスにも abstract を指定する必要があります。

演算子メソッド

演算子メソッドはそれぞれの演算子を定義するメソッドで、Javaの公開メソッドに演算子注釈と呼ばれる注釈を指定したものです。

演算子注釈が一つだけ付与されている

付与された演算子注釈に適した引数や返戻型が宣言されている

public として宣言する

static として宣言 しない

演算子クラス内の他のあらゆる演算子メソッドと名前が衝突しない 1

演算子の一覧や、演算子注釈については 演算子リファレンス を参照してください。

以下は、演算子メソッドの例です。

public abstract class ExampleOperator {

    /**
     * レコードの値に100を設定する。
     * @param hoge 更新するレコード
     */
    @Update
    public void edit(Hoge hoge) {
        hoge.setValue(100);
    }
    ...
}

1

この名前衝突の判定はアンダースコア、大文字、小文字を無視します。

キー注釈

データモデルのグループ化条件やソート条件を記載するには、演算子の仕様に従って注釈 Key 2 をメソッド引数などに指定します。この注釈には、それぞれ下記のような要素を記載できます。

@Key の要素

要素名

記載内容

例

group

グループ化に利用するプロパティ名の一覧。これらのフィールドが全て同じものでグループを構成する。空の配列を指定すると全てを単一のグループにまとめる。

group = "name"

order

順序付けに利用するプロパティ名と、順序の一覧。プロパティを一つも指定しない場合、順序は実装依存となる。フィールド名の前に + (昇順)または - (降順)を指定する。 +, - を省略した場合、昇順に整列する。

order = "+age"

それぞれに指定するプロパティ名は、下記のいずれの形式も利用できます。

snake_case

すべての語を小文字で指定し、 _ (アンダースコア)で区切る。 DMDLの名前と同じ形式 (推奨)。

UPPER_CASE

すべての語を大文字で指定し、 _ (アンダースコア)で区切る。データベースのカラム名でよく利用される形式。

camelCase (Lower Camel Case)

単語の先頭のみを大文字で指定し、先頭の単語だけすべて小文字で指定する。 Javaのフィールド名等の標準規約と同じ形式。

PascalCase (Upper Camel Case)

単語の先頭のみを大文字で指定する。 Javaのクラス名等の標準規約と同じ形式。

Note

このプロパティの命名規約により、利用可能なプロパティ名にいくつかの制限が設けられます。具体的には、 HTMLString のよう形式のプロパティ名が期待した名前にならない、 value_0 のように単語の先頭がアルファベットでないものを正しく認識できない、などが挙げられます。

単一の演算子の中に複数の @Key を指定する場合には、次のことに注意して下さい。

それぞれのキーに出現する group の項目は、同じ個数でなければならない

group の各項目は、それぞれのキーにおいて以下のように計算を行う

同じ位置のそれぞれの項目で等価比較を行う

同じ位置のそれぞれの項目は、完全に同じ型でなければならない

order の項目については上記のような制約はない

それぞれの要素に複数の条件を指定するには、プロパティ名や順序を group = { "a", "b", "c" } のようにカンマ区切りで指定します。

// 名前でグループ化
@Key(group = "name")

// 名前と性別でグループ化
@Key(group = { "name", "sex" })

// 名前でグループ化し、年齢の昇順で整列
@Key(group = "name", order = "+age")

// 名前でグループ化し、収入の昇順, 年齢の降順で整列
@Key(group = "name", order = { "+income", "-age" })

// 全てを単一のグループにまとめ、回数の降順で整列
@Key(group = {}, order = "-count")

See also

キーの指定が必要な演算子については、 演算子リファレンス を参照してください。

2

com.asakusafw.vocabulary.model.Key [https://docs.asakusafw.com/0.10.3/release/api/com/asakusafw/vocabulary/model/Key.html]

Note

Asakusa Framework 0.10.0 より前のバージョンでは、 order での昇順・降順指定は「プロパティ名の 後 に ASC または DESC を指定する」という方式でした。この方式は 0.10.0 以降でも利用可能です。

演算子の多相化

演算子メソッドは入出力するデータモデルに、クラス型以外にもインターフェース型を指定できます。ただし、指定できるインターフェースは射影モデルのみで、演算子メソッドの型引数を宣言してその上限境界に指定します。

@Update
public <T extends Something>
void example(T model) {
     model.setValue(100);
}

See also

演算子の多相化について詳しくは 多相データフロー を参照してください。また、射影モデルについては DMDLユーザーガイド を参照してください。

フレームワークAPI

フレームワークAPIは、演算子メソッドの中で利用できるAsakusa Frameworkが提供するAPI群です。これらのAPIはいずれも演算子クラスの外からは 利用できません 。

Attention

実装上の理由で、現時点のバージョン 0.10.3 では 部分集約 を利用している演算子メソッドから、フレームワークAPIを利用できません。詳しくは 演算子リファレンス を参照してください。

Note

Asakusa DSLのうち、Batch DSLとFlow DSLで記述したJavaのプログラムはいずれもDSLの コンパイル時に 処理されます。対して、Operator DSLで記述したプログラムはアプリケーションの実行時に処理されます。フレームワークAPIはいずれもアプリケーションの実行時のみに有効で、コンパイル時には無効化されています。上記の理由で、 Flow DSL や Batch DSL からこれらのAPIを利用できません。

コンテキストAPI

コンテキストAPIは、バッチ起動時の引数を演算子内で利用するための仕組みを提供します。バッチ起動時には文字列のキー名と値のペア (バッチ引数) を複数指定でき、コンテキストAPIを利用するとキー名に対応する値を演算子の中から参照できます。

このAPIは BatchContext 3 クラスのメソッドから利用します。

コンテキストAPIのメソッド

メソッド名

概要

get

指定したキー名に対応する値を参照する

また、バッチ引数以外にもあらかじめ宣言された変数を利用できます。

あらかじめ宣言された変数

変数名

概要

user

現在のユーザー名。

batch_id

実行中のバッチID。同一の バッチ に対しては常に同じ値になる。

flow_id

実行中のフローID。同一の ジョブフロー に対しては常に同じ値になる。

execution_id

現在の ジョブフロー に対する実行ID。同一のバッチIDやフローIDに対しても、ジョブフローの実行のたびに変化する。同一ジョブフローの実行中は必ず同じ値で、トランザクションを識別するために利用できる。

3

com.asakusafw.runtime.core.BatchContext [https://docs.asakusafw.com/0.10.3/release/api/com/asakusafw/runtime/core/BatchContext.html]

レポートAPI

レポートAPIは、バッチ実行時に発生したエラーや警告などをレポートする仕組みを提供します。標準的な実装では、レポートは実行エンジンのログ機構にリダイレクトされます。

このAPIは Report 4 のクラスメソッドから利用します。

レポートAPIのメソッド

メソッド名

概要

error

「エラー」レベルのレポート

warn

「警告」レベルのレポート

info

「情報」レベルのレポート

致命的な状況に対するレポートの仕組みも用意していますが、このレポートによって処理の流れに影響が出ることはありません。エラーによって処理を強制終了させたい場合などでは、ランタイム例外を演算子メソッドからスローするなどの方法が必要です。

4

com.asakusafw.runtime.core.Report [https://docs.asakusafw.com/0.10.3/release/api/com/asakusafw/runtime/core/Report.html]

Attention

特定のデータに対してレポートのみを行い、その結果を最終的に出力しない場合、コンパイラの最適化によって演算子の処理が省略されてしまう場合があります。上記のような演算子メソッドには、最適化を抑止する注釈 Sticky を併せて指定してください。

Hint

ロギング演算子の利用も検討してください。この演算子は内部的にこのレポートAPIを利用し、自動的に省略の最適化を抑止しています。

ユーティリティAPI

ユーティリティAPIは、Asakusa Frameworkが提供するユーティリティAPI群です。演算子メソッド内での利用を想定しています。

オブジェクトの共有

演算子メソッドは入力レコードやグループごとにフレームワークから呼び出され実行されますが、ある演算子メソッドの呼び出し時に生成したオブジェクトをキャッシュして他の呼び出し時に利用することで、効率的な処理を記述することが可能な場合があります。

Shared 5 クラスは演算子で利用する共有オブジェクトの管理機能を提供します。利用方法はJavadocを参照してください。

5

com.asakusafw.runtime.core.util.Shared [https://docs.asakusafw.com/0.10.3/release/api/com/asakusafw/runtime/core/util/Shared.html]

Operator DSLコンパイラ

Operator DSLコンパイラは作成した 演算子クラス をコンパイルして実行時に必要なクラスや Flow DSL に必要なクラスを生成します。

このコンパイラは、Javaの 注釈プロセッサ [http://www.jcp.org/en/jsr/detail?id=269] の仕組みの上に構築しています。そのため、Operator DSLコンパイラとそれの依存ライブラリを javac コマンドのクラスパスに指定することで、自動的にOperator DSLコンパイラが起動します。

Attention

Operator DSLコンパイラは、後続のアプリケーション開発で必要なクラスを自動生成します。プロジェクトをクリーンビルドする際には、必要なクラスが一時的に足りない状態であるため、コンパイル順序によっては「クラスが見つからない」等の警告メッセージが表示されることがあります。しかし、javacには「ラウンド」という概念があり、現在の処理のラウンドでクラスが見つからなくても、コンパイル中に新しく生成されたソースプログラムを含めて次のラウンドでさらにコンパイルを実行します。これによってコンパイルエラーにはなりませんが、他の場所でコンパイルエラーが発生した際に、上記に関するエラーメッセージが余計に表示されてしまう場合があるようです。

Note

Operator DSLコンパイラに注釈プロセッサの仕組みを採用した理由は、主にIDEとの親和性です。注釈プロセッサはJavaコンパイラの一部のようにふるまうため、注釈プロセッサ内で発生したエラーをコンパイルエラーのようにIDE上に表示させています。

演算子実装クラス

演算子実装クラスは、 演算子クラス を継承した実装クラスです。演算子クラスは抽象クラス ( abstract class ) として宣言し、いくつかの演算子メソッドは本体を持たない抽象メソッドとして宣言していました。

演算子クラスそのものは抽象クラスのためインスタンスを生成できず、実際に利用できないため、演算子実装クラスは具象クラスとして生成されます。また、抽象メソッドとして宣言した演算子メソッドに対して、オーバーライドした具象メソッドを生成します。

演算子実装クラスは、もとの演算子クラスの末尾に Impl をつけた名前で生成されます。演算子メソッドに対する単体テストを行いたい場合には、生成された演算子実装クラスをインスタンス化して行うことを推奨しています。

Caution

ここで生成される具象メソッドは、実行時に利用されないダミーの実装である場合があります。また、生成される実装はコンパイラのバージョンが変わった際に内容が変更される場合もあります。それらの演算子メソッドに対する単体テストは行うべきではありません。

演算子ファクトリ

演算子ファクトリは、 演算子クラス に宣言された演算子をFlow DSLから利用できるようにするためのクラスです。このクラスには、次の2つの要素が宣言されます。

演算子オブジェクトクラス

Flow DSLでは、データフロー上の演算子を表すために「演算子オブジェクト」というものを利用します。これは、演算子のデータフロー内での接続状態を表し、さらにその演算子の出力を表す「ポート」をフィールドとして保持しています。演算子オブジェクトクラスはこのオブジェクトの元になるクラスで、演算子ファクトリの内部クラスとして宣言されます。

演算子ファクトリメソッド

上記の演算子オブジェクトを生成するファクトリメソッドです。このメソッドは、演算子への入力を表す「ポート」を引数にとります。

演算子ファクトリクラスは、もとの演算子クラスの末尾に Factory をつけた名前で生成されます。また、演算子ファクトリメソッドはもとの演算子メソッドと同じ名前で、演算子オブジェクトクラスはもとの演算子メソッドをJavaのクラス名の規約に変換した名前 6 がつけられます。

演算子の多相化 を行っている場合、対応する演算子オブジェクトクラスとファクトリメソッドにはそれぞれもとの演算子メソッドで宣言した型引数が自動的に宣言されます。

6

メソッド名の最初の文字を大文字に変換します

フロー演算子

Operator DSLコンパイラは、 フロー部品 に対する演算子 (フロー演算子) も生成します。フロー部品には「 演算子実装クラス 」が不要であるため、「 演算子ファクトリ 」のみを生成します。通常の演算子ファクトリとは次のような相違があります。

演算子ファクトリメソッド名は常に create

演算子オブジェクトクラス名はフロー部品の名前と同じ

See also

フロー演算子については 演算子リファレンス を参照してください。

演算子とスレッド安全性

バッチアプリケーションの実行時において、演算子(実装)クラスのインスタンスは次の規則で生成しています。

同一のバッチ内の異なる箇所から演算子メソッドを起動する場合、そのインスタンスは必ず起動元ごとに異なる

異なるスレッドから演算子メソッドを起動する場合、そのインスタンスは必ずスレッドごとに異なる

つまり、バッチアプリケーションがある演算子メソッドを起動してから終了するまで、その演算子メソッドが属するインスタンスはそのメソッドのみが占有している状態になります。そのため、演算子クラスに宣言したインスタンスフィールドの状態は、演算子メソッドごとに独立したものになります。

なお、演算子クラスにクラス( static )フィールドを宣言した場合、そのフィールドは複数のスレッド・演算子メソッドから参照される場合があるため、スレッド安全性に注意が必要です。

なお、以下はスレッドや演算子メソッドをまたいで共有される場合があります。

ビュー オブジェクト ( View , GroupView ) とその内容

以下の演算子の「マスタデータ」に関するオブジェクト

マスタ確認演算子

マスタ分岐演算子

マスタつき更新演算子

マスタ選択

上記に該当するオブジェクトは変更すべきではありません。

Flow DSL

Flow DSLは演算子を組み合わせてデータフローの構造を記述するDSLです。このDSLではデータフローの構造を非循環有向グラフ (Directed Acyclic Graph: DAG)を構造の通りにそのまま記述できます。

Flow DSLで記述できる構造は2種類あり、それぞれ異なる性質を持ちます。

ジョブフロー

外部システムからデータを取り出して、外部システムにデータを書き出すデータフロー。データフローの入出力にはそれぞれ インポータ記述 と エクスポータ記述 を付与して外部と連携する方法を記述する。

フロー部品

データフローそのものを演算子として定義する。ここで記述したデータフローは、Flow DSLで演算子として利用できる。

いずれの構造においても、Flow DSLではデータフローの入出力と演算子の入出力をつなぎ合わせて、データ処理の流れを表します。

ジョブフロー

ジョブフローはFlow DSLのトップレベルの要素で、外部システムからデータを読み出し、データを加工して、外部システムにデータを書き戻すという一連のデータ処理を記述できます。

外部システムとの連携は インポータ記述 や エクスポータ記述 でそれぞれ入出力方法を記述します。また、外部入出力と Operator DSL で作成した演算子の入出力を フロー記述メソッド 内で組み合わせて、データフローの構造を記述します。

インポータ記述

インポータ記述はジョブフローの入力もととなるデータソースを記述するクラスです。データソースごとに指定されたクラスを継承して、必要な情報を記載します。

Asakusa Frameworkは標準でDirect I/OやWindGateというデータソースを提供しています。詳しくは データの直接入出力 - Direct I/O , 外部システムとの連携 - WindGate をそれぞれ参照してください。

Caution

インポータ記述の中で定義するメソッドは、 Batch DSLコンパイラ の コンパイル中に 起動されます。そのため、 フレームワークAPI はこの中では利用できません。

Hint

インポータ記述の多くは getDataSize() というメソッドを共通して持っています。このメソッドを上書きし、適切なデータサイズを指定することで、コンパイラはそれをヒントに最適化を行います。

Note

インポータ記述はいずれも ImporterDescription 7 インターフェースの実装クラスとなります。ただし、このインターフェースだけを実装してもデータソースを利用することはできません。これらは、 Operator DSLコンパイラ のコンパイラプラグインを追加することで、新しいデータソースを利用できるようになります。

7

com.asakusafw.vocabulary.external.ImporterDescription [https://docs.asakusafw.com/0.10.3/release/api/com/asakusafw/vocabulary/external/ImporterDescription.html]

エクスポータ記述

エクスポータ記述はジョブフローの結果を出力する先となるデータソースを記述するクラスです。データソースごとに指定されたクラスを継承して、必要な情報を記載します。

Asakusa Frameworkは標準でDirect I/OやWindGateというデータソースを提供しています。詳しくは データの直接入出力 - Direct I/O , 外部システムとの連携 - WindGate をそれぞれ参照してください。

Caution

エクスポータ記述の中で定義するメソッドは、 Batch DSLコンパイラ の コンパイル中に 起動されます。そのため、 フレームワークAPI はこの中では利用できません。

Note

エクスポータ記述はいずれも ExporterDescription 8 インターフェースの実装クラスとなります。インポータ記述と同様に、このインターフェースだけを実装してもデータソースを利用することはできません。

8

com.asakusafw.vocabulary.external.ExporterDescription [https://docs.asakusafw.com/0.10.3/release/api/com/asakusafw/vocabulary/external/ExporterDescription.html]

ジョブフロークラス

それぞれのジョブフローは、データフローのベースクラスである FlowDescription 9 を継承したJavaのクラスとして宣言します。このクラスには以下のような制約があります。

public として宣言されている

abstract として宣言されて いない

FlowDescription を継承する

注釈 JobFlow 10 を付与する

型引数を宣言していない

明示的なコンストラクターを一つだけ宣言する

また、注釈 JobFlow の要素 name にこのバッチの名前を指定します。ここで指定する名前は、 Javaの変数名のうち、ASCIIコード表に収まるもののみでなければなりません。

以下はジョブフロークラスの例です。

package com.example.business.jobflow;

import com.asakusafw.vocabulary.flow.*;

@JobFlow(name = "stock")
public class StockJob extends FlowDescription {

}

9

com.asakusafw.vocabulary.flow.FlowDescription [https://docs.asakusafw.com/0.10.3/release/api/com/asakusafw/vocabulary/flow/FlowDescription.html]

10

com.asakusafw.vocabulary.flow.JobFlow [https://docs.asakusafw.com/0.10.3/release/api/com/asakusafw/vocabulary/flow/JobFlow.html]

ジョブフローコンストラクタ

ジョブフローの入出力は、ジョブフロークラスのコンストラクタで宣言します。これには次のような制約があります。

public として宣言されている

型引数を宣言していない

In 11 型の仮引数を一つ以上宣言し、それぞれ型引数にデータモデル型を指定する

Out 12 型の仮引数を一つ以上宣言し、それぞれ型引数にデータモデル型を指定する

In , Out 以外の仮引数を宣言しない

それぞれの In 型の引数は、ジョブフローへの1つ分の入力を表しています。この仮引数には、注釈 Import 13 を付与し、要素 name に入力の名前を、要素 description に インポータ記述 のクラスリテラルを指定します。ここで指定したインポート処理の結果が、この入力を通して利用できます。

同様に、それぞれの Out 型の引数は、ジョブフローからの1つ分の出力を表しています。この仮引数には、注釈 Export 14 を付与し、要素 name に出力の名前を、要素 description に エクスポータ記述 のクラスリテラルを指定します。この出力に対するジョブフローの結果が、エクスポート処理で書きだされます。

それぞれに指定する Import や Export にはそれぞれ次のような制約があります。

要素 name にはJavaの変数名のうち、ASCIIコード表に収まるもののみ指定できる

それぞれの要素 name に指定する文字列が重複しない

要素 description に指定した記述と、型引数のデータモデルの型が一致する

Hint

name が重複してはいけない範囲は、それぞれの Import と Export の中のみです。 Import と Export の組み合わせで重複しても構いません。

以下はジョブフローコンストラクタの例です。

In<Shipment> shipmentIn;
In<Stock> stockIn;
Out<Shipment> shipmentOut;
Out<Stock> stockOut;

/**
 * コンストラクタ。
 * @param shipmentIn 処理対象の注文情報
 * @param stockIn 処理対象の在庫情報
 * @param shipmentOut 処理結果の注文情報
 * @param stockOut 処理結果の在庫情報
 */
public StockJob(
        @Import(name = "shipment", description = ShipmentFromDb.class)
        In<Shipment> shipmentIn,
        @Import(name = "stock", description = StockFromDb.class)
        In<Stock> stockIn,
        @Export(name = "shipment", description = ShipmentToDb.class)
        Out<Shipment> shipmentOut,
        @Export(name = "stock", description = StockToDb.class)
        Out<Stock> stockOut) {
    this.shipmentIn = shipmentIn;
    this.stockIn = stockIn;
    this.shipmentOut = shipmentOut;
    this.stockOut = stockOut;
}

11

com.asakusafw.vocabulary.flow.In [https://docs.asakusafw.com/0.10.3/release/api/com/asakusafw/vocabulary/flow/In.html]

12

com.asakusafw.vocabulary.flow.Out [https://docs.asakusafw.com/0.10.3/release/api/com/asakusafw/vocabulary/flow/Out.html]

13

com.asakusafw.vocabulary.flow.Import [https://docs.asakusafw.com/0.10.3/release/api/com/asakusafw/vocabulary/flow/Import.html]

14

com.asakusafw.vocabulary.flow.Export [https://docs.asakusafw.com/0.10.3/release/api/com/asakusafw/vocabulary/flow/Export.html]

フロー記述メソッド

データフローでの処理内容は、 FlowDescription クラスの describe メソッドをオーバーライドして記述します。ここでは、コンストラクタで受け取った入出力と、 Operator DSL で記述した演算子を組み合わせてデータ処理の流れを記述します。

作成した演算子を利用するには、その演算子クラスに対応する 演算子ファクトリ を経由します。また、「コア演算子」という組み込みの演算子ファクトリも用意されています。コア演算子については 演算子リファレンス を参照してください。

以下は、フロー記述メソッドの例です。

In<Shipment> shipmentIn;
In<Stock> stockIn;
Out<Shipment> shipmentOut;
Out<Stock> stockOut;

@Override
protected void describe() {
    CoreOperatorFactory core = new CoreOperatorFactory();
    StockOpFactory op = new StockOpFactory();

    // 処理できない注文をあらかじめフィルタリング
    CheckShipment check = op.checkShipment(shipmentIn);
    core.stop(check.notShipmentped);
    core.stop(check.completed);

    // 在庫引当を行う
    Cutoff cutoff = op.cutoff(stockIn, check.costUnknown);

    // 結果を書き出す
    shipmentOut.add(cutoff.newShipments);
    stockOut.add(cutoff.newStocks);
}

Caution

フロー記述メソッドは、 Batch DSLコンパイラ の コンパイル中に 起動されます。そのため、 フレームワークAPI はこの中では利用できません。

Note

フロー記述メソッドの記述は、主にデータフローの設計書を意識しています。設計書に記載されたデータフローの構造のうち、プロセスを演算子に置き換え、「この演算子の入力は、どこのデータを使えばいいか」ということを意識しながら演算子を配置していくことで、目的のデータフローを記述できます。ただし、グラフ構造をテキストで記述するとやはり読みにくくなってしまうため、テキスト以外の記述方法も検討しています。

フロー部品

フロー部品は名前のとおり「データフローの部品」を定義する構造です。ここで定義したデータフローは、ほかのデータフローから「フロー演算子」とよばれる演算子として利用できます。フロー部品の中にフロー演算子を含めることもでき、複雑なデータフローを階層化して取り扱えます。

ジョブフローに対して、フロー部品は次のような特徴があります。

外部入出力を定義しない

フロー部品単体では外部入出力を定義できず、かならずいずれかのジョブフローの中で利用されることになります。このため、ジョブフローで指定したインポートやエクスポートの指定は不要です。

フロー演算子を自動生成する

Operator DSLコンパイラ を利用すると、フロー部品に対応するフロー演算子を自動的に生成します。

値引数を利用できる

フロー部品には入出力以外に任意の引数を指定できます。一部の値のみが異なる複数のデータフローをフロー部品として抽出すると、データフローの再利用性が高まります。

型引数を利用できる

フロー部品は 多相データフロー に対応しています。データフロー内で利用するデータモデルの種類を型引数として宣言でき、内部では多相化した演算子を利用できます。

Note

フロー部品はデータフローの構造化と再利用を意識して導入した仕組みです。またフロー部品は単体テストの単位ともなるので、意味のある単位で構成することでデータフローのテストが容易になります。

フロー部品クラス

それぞれのフロー部品は、 ジョブフロー と同様に FlowDescription 15 を継承したJavaのクラスとして宣言します。このクラスには以下のような制約があります。

public として宣言されている

abstract として宣言されていない

FlowDescription を継承する

注釈 FlowPart 16 を付与する

明示的なコンストラクターを一つだけ宣言する

Hint

フロー部品クラスはジョブフロークラスと異なり、型引数の宣言が可能です。詳しくは 多相データフロー を参照してください。

以下はフロー部品クラスの例です。

package com.example.business.flowpart;

import com.asakusafw.vocabulary.flow.*;

@FlowPart
public class StockPart extends FlowDescription {

}

15

com.asakusafw.vocabulary.flow.FlowDescription [https://docs.asakusafw.com/0.10.3/release/api/com/asakusafw/vocabulary/flow/FlowDescription.html]

16

com.asakusafw.vocabulary.flow.FlowPart [https://docs.asakusafw.com/0.10.3/release/api/com/asakusafw/vocabulary/flow/FlowPart.html]

フロー部品コンストラクタ

フロー部品の入出力は、ジョブフローと同様にコンストラクタで宣言します。これには次のような制約があります。

public として宣言されている

型引数を宣言していない

In 17 型の仮引数を一つ以上宣言し、それぞれ型引数にデータモデル型または型変数を指定する

Out 18 型の仮引数を一つ以上宣言し、それぞれ型引数にデータモデル型または型変数を指定する

それぞれの In 型の引数は、フロー部品への1つ分の入力を表しています。同様に、それぞれの Out 型の引数は、フロー部品からの1つ分の出力を表しています。

Hint

フロー部品のコンストラクタには、入出力以外にも任意の引数を利用できます。

以下はフロー部品コンストラクタの例です。

In<Shipment> shipmentIn;
In<Stock> stockIn;
Out<Shipment> shipmentOut;
Out<Stock> stockOut;

/**
 * コンストラクタ。
 * @param shipmentIn 処理対象の注文情報
 * @param stockIn 処理対象の在庫情報
 * @param shipmentOut 処理結果の注文情報
 * @param stockOut 処理結果の在庫情報
 */
public StockPart(
        In<Shipment> shipmentIn,
        In<Stock> stockIn,
        Out<Shipment> shipmentOut,
        Out<Stock> stockOut) {
    this.shipmentIn = shipmentIn;
    this.stockIn = stockIn;
    this.shipmentOut = shipmentOut;
    this.stockOut = stockOut;
}

17

com.asakusafw.vocabulary.flow.In [https://docs.asakusafw.com/0.10.3/release/api/com/asakusafw/vocabulary/flow/In.html]

18

com.asakusafw.vocabulary.flow.Out [https://docs.asakusafw.com/0.10.3/release/api/com/asakusafw/vocabulary/flow/Out.html]

フロー部品のフロー記述

フロー部品のフロー記述は、ジョブフローと同様です。フロー記述メソッド を参照してください。

データフローのコンパイル

Asakusa Frameworkでは、通常Flow DSLのプログラムを直接コンパイルしません。これらはバッチに含めた状態でコンパイルされます。詳しくは Batch DSLコンパイラ を参照してください。

なお、フロー部品を Operator DSLコンパイラ に掛けると「フロー演算子」を作成します。これはジョブフローやフロー部品に、他のフロー部品を組み込むための演算子です。フロー演算子については、 演算子リファレンス を参照してください。

Batch DSL

Batch DSLはデータフローを組み合わせて複雑なバッチ処理の流れを記述するDSLです。それぞれのデータフローを処理する順序を、依存関係のグラフ構造で記述できます。

バッチ

バッチはBatch DSLに出現する唯一の要素で、「エンドユーザーから見たバッチ処理の単位」を表すことを想定しています。ジョブフロー は外部システムからの入力を取り込んで、処理結果を出力するまでの一連の流れを表しています。バッチはそれらをさらに組み合わせて、意味のある一連の処理を記述できます。

Batch DSLで記述する内容は、主に「ジョブフローの実行順序」です。それぞれのジョブフローの実行順序を、ジョブフロー間の依存関係を元に記述します。依存関係のあるジョブフローは、手前のジョブフローの処理が完了するまでブロックされ、それらがすべて終了したのちにジョブフローの処理が開始されます。

Note

Batch DSLではデータフロー以外の処理を連携できるようにする計画があります。たとえば、外部システムからデータを取り込むようなスクリプトを後続のデータフロー処理に先立って起動するなどです。

バッチクラス

それぞれのバッチは、バッチクラスのベースクラスである BatchDescription 19 を継承したJavaのクラスとして宣言します。このクラスには以下のような制約があります。

public として宣言されている

abstract として宣言されて いない

BatchDescription を継承する

注釈 Batch 20 を付与する

型引数を宣言していない

明示的なコンストラクタを宣言しない

また、注釈 Batch の要素 name にこのバッチの名前を指定します。ここで指定する名前は、 Javaのパッケージ名のうち、ASCIIコード表に収まるもののみでなければなりません。

以下はバッチクラスを作成する例です。

package com.example.batch;

import com.asakusafw.vocabulary.batch.*;

@Batch(name = "example")
public class ExampleBatch extends BatchDescription {

}

19

com.asakusafw.vocabulary.batch.BatchDescription [https://docs.asakusafw.com/0.10.3/release/api/com/asakusafw/vocabulary/batch/BatchDescription.html]

20

com.asakusafw.vocabulary.batch.Batch [https://docs.asakusafw.com/0.10.3/release/api/com/asakusafw/vocabulary/batch/Batch.html]

バッチ注釈

バッチクラスに指定した注釈 @Batch には、 name 以外にも様々な属性を指定できます。

@Batch の属性

属性名

型

既定値

概要

name

文字列

なし

バッチの名前 (Batch ID)

comment

文字列

"" (空)

バッチのコメント

parameters

Parameter[] の配列

{} (空)

利用可能なバッチ引数の一覧 (形式は後述) 21

strict

boolean

false

true を指定した場合に parameters に指定した引数以外を利用できなくなる

上記のうち parameters を指定すると、このバッチで利用可能なバッチ引数の詳細を指定できます。さらに strict に true を指定すると、 parameters 以外のバッチ引数を指定できなくなります。

この parameters では注釈 @Parameter 22 を利用して個々のバッチ引数を指定します。

@Parameter の属性

属性名

型

既定値

概要

key

文字列

なし

バッチ引数のキー

comment

文字列

"" (空)

バッチ引数のコメント

required

boolean

true

true ならば必須引数、 false ならば省略可能

pattern

文字列

".*" (すべて)

バッチ引数の値に指定可能な文字列を表す正規表現

上記のうち、 pattern には java.util.regex.Pattern 形式の正規表現を指定できます。この pattern が省略された場合には、バッチ引数の値に全ての文字列を利用できます。

Note

コマンドラインインターフェース - Asakusa CLI が提供する asakusa run コマンドは、バッチ注釈を利用してバッチ引数のチェックを行います。

以下は、 @Batch を記述するサンプルです。

package com.example.batch;

import com.asakusafw.vocabulary.batch.*;
import com.asakusafw.vocabulary.batch.Batch.*;

@Batch(
    name = "com.example",
    comment = "サンプル用のバッチ",
    parameters = {
        @Parameter(key = "date", comment = "業務日付", pattern = "\\d{4}-\\d{2}-\\d{2}"),
        @Parameter(key = "memo", comment = "実行メモ", required = false)
    },
    strict = true
)
public class ExampleBatch extends BatchDescription {

}

21

バッチ引数については コンテキストAPI も参照してください。

22

com.asakusafw.vocabulary.batch.Batch.Parameter [https://docs.asakusafw.com/0.10.3/release/api/com/asakusafw/vocabulary/batch/Batch.Parameter.html]

バッチ記述メソッド

バッチの内容は、 BatchDescription クラスの describe メソッドをオーバーライドして記述します。このメソッドの中には、ジョブフローの依存関係を記述してバッチ全体を構築するようなプログラムを書きます。以下はバッチメソッドを記述する例です。

@Override
protected void describe() {
    Work first = run(FirstFlow.class).soon();
    Work second = run(SecondFlow.class).after(first);
    Work para = run(ParallelFlow.class).after(first);
    Work join = run(JoinFlow.class).after(second, para);
    ...
}

バッチの内部で実行するジョブフローは、 BatchDescription クラスから継承した run() メソッドで指定します。同メソッドには対象のジョブフロークラスのクラスリテラルを指定し、そのままメソッドチェインで soon() や after() メソッドを起動します。

soon メソッドはバッチの内部で最初に実行されるジョブフローを表し、 after メソッドは依存関係にある処理を引数に指定して、それらの処理が全て完了後に実行されるジョブフローを表します。

Caution

バッチ記述メソッドは、 Batch DSLコンパイラ の コンパイル中に 起動されます。そのため、 フレームワークAPI はこの中では利用できません。

Batch DSLコンパイラ

Batch DSLコンパイラは、バッチクラスから次のものを生成します。

外部入出力を行うための設定情報など

データフロー処理を行うプログラム群

上記の一連の流れを規定するワークフロー記述

Batch DSLコンパイラが生成するバッチアプリケーション

Batch DSLコンパイラが生成するバッチアプリケーションには以下のものが含まれます。

外部入出力を行うための設定情報

Batch DSLコンパイラはコンパイル対象のバッチアプリケーションのジョブフロー記述の情報などから、Direct I/OやWindGateがデータの入出力を行うための設定情報を生成します。

この設定情報はバッチアプリケーション実行時にDirect I/OやWindGateが参照し、その設定内容に応じて入出力データを決定したり、入出力時に行われる制御（排他制御など）を行います。

データフロー処理を行うプログラム群

Batch DSLコンパイラはバッチアプリケーションに含まれるOperator DSLやFlow DSLの内容から、実行プラットフォーム向けのプログラム群を生成します。

Batch DSLコンパイラは実行プラットフォームごとに対応するコンパイラを提供します。各コンパイラはコンパイル時の動作や生成プログラムの内容に関する設定を行うための「コンパイルオプション」を利用可能です。

各コンパイラによって利用できるコンパイルオプションは異なります。各コンパイラのコンパイルオプションについては、以下のドキュメントを参照してください。

Asakusa on Spark リファレンス - Asakusa DSL Compiler for Spark リファレンス

Asakusa on M3BPリファレンス - DSL Compiler for M3BPリファレンス

Asakusa on MapReduce リファレンス - Asakusa DSL Compiler for MapReduce リファレンス

ワークフロー記述

ワークフロー記述は、コンパイルされたバッチを実行する際に入出力や実行プラットフォーム向けのプログラムの実行順序を記述したものです。これはワークフローエンジンごとに生成される記述で、対応するコンパイラプラグインをコンパイル時に指定します。

標準では、Batch DSLコンパイラはYAESSというジョブ実行ツールのためのワークフロー記述である「YAESSスクリプト」を生成します。

YAESSについては アプリケーションの実行 - YAESS を参照してください。

モジュールの取り込み

開発環境の構成によっては、バッチアプリケーションを構成するモジュールを分割して管理したいケースがあります。例えば、以下のような場合です。

複数のプロジェクトでデータモデルの定義を共有する

複数のプロジェクトでビジネスロジックを共有する

外部入出力を含むジョブフローとそれ以外の部分を分離する

一部の単体テストケースを分離して管理する

このような場合、アプリケーションプロジェクトを分割し、それぞれのモジュールを個別に生成、管理します。

あるアプリケーションプロジェクトからモジュールの取り込みを行いたい場合、取り込まれる側のクラスライブラリ内に META-INF/asakusa/fragment というファイル (以下、マーカーファイル) を含めた上で、コンパイラのクラスパスに上記クラスライブラリを追加してください。

Attention

マーカーファイルを含むクラスライブラリを取り込む際、同じパスのファイルが複数含められていると正しく動作しません。

Hint

マーカーファイルによる取り込みは テストドライバー を利用する際にも有効です。この場合、テストドライバーを起動した際のクラスパスに含められたクラスライブラリから、マーカーファイルを検索します。

なお、テストドライバーを実行する際に、起点となるジョブフローやバッチを含むクラスライブラリは自動的に取り込まれます。

演算子リファレンス

この文書では、Asakusa Frameworkが提供する演算子について個々に紹介します。

Asakusa DSLの演算子

Asakusa FrameworkのOperator DSLとFlow DSLでは、それぞれ演算子を利用しています。

前者のOperator DSLでは、主に演算子を「作成」します。 Asakusa Frameworkが提供するのは演算子の「種類」であって、それぞれの演算子の細かな挙動はOperator DSLでカスタマイズできます。

後者のFlow DSLでは、主に演算子を「複合」します。 Operator DSLで作成する演算子はデータフローの「部品」であり、これらを複合して複雑なデータフローを構築することになります。

レコードとグループ

それぞれの演算子が処理するデータの単位は、「レコード」または「グループ」のいずれかです。

レコード

データフローに流れるデータ1つ分。 Asakusa DSLでは「データモデルオブジェクト」として表現される。

グループ

レコードを特定のキーでグループ化したもの。 Asakusa DSLでは、データモデルオブジェクトのリストや反復子などで表現される。

キー注釈

Operator DSLでは上記のグループを作成するために、 Key 1 という注釈を多用します。これは、グループ化のための方法や、グループ内での整列順序を指定するためのものです。詳しくは Asakusa DSLユーザーガイド - キー注釈 を参照してください。

1

com.asakusafw.vocabulary.model.Key [https://docs.asakusafw.com/0.10.3/release/api/com/asakusafw/vocabulary/model/Key.html]

演算子の分類

それぞれの演算子は、処理の内容ごとにいくつかに分類できます。

フロー制御演算子

データの流れそのものを制御する。

データ操作演算子

データフローに流れるデータを加工する。

結合演算子

複数のレコードを結合する。

集計演算子

レコードをグループごとに集計する。

特殊演算子

上記の分類に含まれない特別な演算子。

コア演算子とユーザー演算子

演算子を実装方法の面から2種類に分類できます。

コア演算子

Asakusa Frameworkが APIとして 提供する演算子。この種類の演算子はOperator DSLで記述する必要はなく、Flow DSLから直接利用できる。

ユーザー演算子

演算子の種類ごとに演算子注釈のみを提供している演算子。この種類の演算子を利用するには、Operator DSLで必要な演算子メソッドを定義する必要がある。なお、ユーザー演算子にもメソッド本体の実装が必要なものと不要なものに分かれています。

Flow DSLでコア演算子を利用する場合、一般的に CoreOperatorFactory 2 というファクトリクラスが提供するメソッドを使用します。また、上記ファクトリクラスと同名のクラスメソッド群を持つ CoreOperators 3 も利用可能です。

2

com.asakusafw.vocabulary.flow.util.CoreOperatorFactory [https://docs.asakusafw.com/0.10.3/release/api/com/asakusafw/vocabulary/flow/util/CoreOperatorFactory.html]

3

com.asakusafw.vocabulary.flow.util.CoreOperators [https://docs.asakusafw.com/0.10.3/release/api/com/asakusafw/vocabulary/flow/util/CoreOperators.html]

演算子の性能特性

それぞれの演算子はその性能特性から、いくつかの種類に分類できます。

Extract 系演算子

もっとも単純な演算子の種類で、入力データからデータモデルオブジェクトを一つずつ取り出して処理を行います。

この種類は並列分散処理が比較的容易で、データサイズが大きくなっても、コンピューターのCPUの個数やクラスターの台数などを増大させることで性能を向上させられるケースが多くあります。ほとんどのコア演算子や、更新演算子、抽出演算子などはこの Extract 系演算子に含まれています。

CoGroup 系演算子

入力データを指定した条件でグループごとに分割し、それぞれのグループを一つずつ取り出して処理を行います。

この種類は、グループごとにデータを分割する操作において、データのコピー・移動や待ち合わせが発生してしまいます。そのため、分散処理を行う際にはこの処理がバッチ全体のボトルネックになる場合があります。

また、分割したグループの大きさに偏りがある場合、処理が特定のノードに集中してしまう場合もあります。

グループ整列演算子や、グループ結合演算子などがこの CoGroup 系演算子に含まれています。

Join 系演算子

入力データに、別の入力データを結合して処理を行います。

この演算子は「トランザクション入力」と「マスタ入力」という2つの入力をとり、マスタ入力のデータが十分に小さな場合に Extract 系演算子と同程度の性能を発揮します。そうでなく、マスタ入力のデータが大きな場合にはおよそ CoGroup 系演算子程度の性能になります。

マスタ結合演算子や、マスタ付き更新演算子などがこの Join 系演算子に含まれています。

Fold 系演算子

入力データを指定した条件でグループごとに分割し、それぞれのグループを集計する処理を行います。

この種類は CoGroup 系演算子と似通っていますが、コンパイラの設定や、処理系によっては CoGroup 系よりも効率よく動作します。

単純集計演算子や、畳み込み演算子などがこの Fold 系演算子に含まれています。

演算子の表記

この文書での演算子に関する表記を説明します。

コア演算子の表記

コア演算子は次のような表で表記します。

コア演算子の表記

項目

内容

分類

“コア”

導入

この演算子が導入されたフレームワークのバージョン

メソッド

CoreOperatorFactory 内のメソッド名

性能特性

Extract | CoGroup | Join | Fold

入力数

この演算子への入力数

出力数

この演算子からの出力数

ユーザー演算子の表記

ユーザー演算子は次のような表で表記します。

ユーザー演算子の表記

項目

内容

分類

“ユーザー”

導入

この演算子が導入されたフレームワークのバージョン

演算子注釈

演算子注釈の名前

本体の実装

“必要”または”不要” 4

性能特性

Extract | CoGroup | Join | Fold

入力数

この演算子への入力数

出力数

この演算子からの出力数

ビュー引数

この演算子にビュー引数を指定可能かどうか 5

値引数

この演算子に値引数を指定可能かどうか

型引数

この演算子に型引数を指定可能かどうか 6

4

本体の実装が不要なユーザー演算子は、抽象メソッドとして宣言します。

5

ビュー引数については、 ビューAPI を参照してください。

6

型引数は多相演算子で使用します。詳しくは 多相データフロー を参照してください。

入出力の表記

それぞれの入出力は、次のような項目を表記します。

入出力の表記

項目

内容

分類

“入力” または “出力”

名前

標準的な名前

単位

処理単位 (“レコード”, “グループ”)

型

データの種類

備考

備考欄

演算子メソッドの表記

演算子メソッドの形式は、次のような項目を表記します。

演算子メソッドの表記

項目

内容

分類

返戻値または引数1～

対応

演算子の入出力との対応

型

指定する型

キー

Key の指定

備考

備考欄

「型」には主に次のようなものがあります。

モデル

データモデル型

リスト

データモデル型を要素に取る List 7

ビュー

データモデル型を要素に取る View および GroupView 8

結果

データモデル型を要素に取る Result 9

プリミティブ

Javaのプリミティブ型、または文字列型

列挙型

Javaの列挙型 ( enum )

Javaの型

Javaの対応する型

7

java.util.List

8

com.asakusafw.runtime.core.View [https://docs.asakusafw.com/0.10.3/release/api/com/asakusafw/runtime/core/View.html] および com.asakusafw.runtime.core.GroupView [https://docs.asakusafw.com/0.10.3/release/api/com/asakusafw/runtime/core/GroupView.html] ビューについては、 ビューAPI を参照してください。

9

com.asakusafw.runtime.core.Result [https://docs.asakusafw.com/0.10.3/release/api/com/asakusafw/runtime/core/Result.html] 演算子の出力となるデータモデルオブジェクトを保持します。 add メソッドにより複数のオブジェクトを追加することができます。

フロー制御演算子

フロー制御系の演算子は、主にデータフローの構造を制御するための演算子です。

分岐演算子

レコードを入力にとって、レコードの内容に応じていずれかの出力にレコードを振り分ける演算子です。「条件に応じて出力先を変える」などの用途に利用できます。

分岐演算子の概要

項目

説明

分類

ユーザー

導入

0.1

演算子注釈

Branch 10

本体の実装

必要

性能特性

Extract

入力数

1

出力数

任意

ビュー引数

指定可能

値引数

指定可能

型引数

指定可能

分岐演算子の入出力

分類

名前

単位

型

備考

入力

in

レコード

任意

出力

(任意)

レコード

inと同様

任意の個数を指定可

10

com.asakusafw.vocabulary.operator.Branch [https://docs.asakusafw.com/0.10.3/release/api/com/asakusafw/vocabulary/operator/Branch.html]

分岐演算子の実装

分岐演算子の演算子メソッドには次のような情報を指定します。

分岐演算子の実装

分類

対応

型

キー

備考

返戻

全出力

列挙型

不可

列挙定数ごとに出力

引数1

入力

モデル

不可

ビュー引数

入力

ビュー

任意

値引数

なし

プリミティブ

不可

この演算子は一つの引数を取り、分岐先を表現する列挙定数を返します。

返戻型に指定する列挙型は、分岐先の出力名を表しています。メソッドから列挙定数を返すと、その時点の引数に渡された入力が、返した列挙定数に対応する出力に渡されます。

引数には同メソッドで宣言した型変数を利用できますが、 戻り値の型に型変数を含めることはできません。

分岐演算子の演算子メソッドは、一般的な演算子メソッドの要件の他に、 下記の要件をすべて満たす必要があります。

返戻型には分岐先を表現する列挙型を指定する

その列挙型は、public として宣言されている

その列挙型は、一つ以上の列挙定数を持つ

以下の引数を宣言する

データモデルオブジェクト型の引数

以下の修飾子を付与する

(特になし)

以下の修飾子は付与しない

abstract

Attention

分岐演算子の内部では、入力の内容を変更しないようにしてください。そのような動作を期待する場合、 更新演算子 を利用するようにしてください。

以下は実装例です。

public abstract class OperatorClass {
    ...

    /**
     * レコードの状態ごとに処理を分岐する。
     * @param hoge 対象のレコード
     * @return 分岐先を表すオブジェクト
     */
    @Branch
    public Status select(Hoge hoge) {
        int price = hoge.getPrice();
        if (price < 0) {
            return Status.ERROR;
        }
        if (price >= 1000000) {
            return Status.EXPENSIVE;
        }
        return Status.CHEAP;
    }

    /**
     * 値段に関するレコードの状態。
     */
    public enum Status {
        /**
         * 高い。
         */
        EXPENSIVE,

        /**
         * 安い。
         */
        CHEAP,

        /**
         * エラー。
         */
        ERROR,
    }

    ...
}

合流演算子

複数の入力を合流して、単一の出力にまとめる演算子です。分岐演算子 の逆の動作を行い、SQLの UNION ALL のように動きます。

合流演算子の概要

項目

説明

分類

コア

導入

0.1

メソッド

confluent

性能特性

Extract

入力数

任意

出力数

1

合流演算子の入出力

分類

名前

単位

型

備考

入力

(任意)

レコード

任意

任意の入力数だが、全て同じ型

出力

out

レコード

入力と同様

合流演算子の実装

合流演算子はコア演算子に分類されるため、Operator DSLでの実装はありません。 Flow DSLからは次のように利用します。

In<Hoge> in1, in2, in3;
Out<Hoge> out;

@Override
protected void describe() {
    CoreOperatorFactory core = new CoreOperatorFactory();
    Confluent<Hoge> op = core.confluent(in1, in2, in3);
    out.add(op);
}

複製演算子

レコードを入力にとって、同じ内容のレコードを複数の出力にそれぞれ出力する演算子です。

複製演算子の概要

項目

説明

分類

コア

導入

0.1

メソッド

特殊 11

性能特性

Extract

入力数

1

出力数

任意

複製演算子の入出力

分類

名前

単位

型

備考

入力

in

レコード

任意

出力

(任意)

レコード

inと同様

任意の個数

11

データの複製は同一の出力を何度も利用するだけで実現できるため、特別なメソッドを用意していません。

複製演算子の実装

複製演算子はコア演算子に分類されるため、Operator DSLでの実装はありません。 Flow DSLからは演算子からの出力を複数回利用すると、複製演算子と同じ効果を得られます。

Out<Hoge> out1, out2, out3;

@Override
protected void describe() {
    ...
    SomeOperator op = ...;
    out1.add(op.out);
    out2.add(op.out);
    out3.add(op.out);
}

データ操作演算子

データ操作系の演算子は、主にレコードを加工したり変形したりするための演算子です。

更新演算子

レコードの内容を更新する演算子です。レコードの型そのものを変更したい場合には、 変換演算子 を利用します。

更新演算子の概要

項目

説明

分類

ユーザー

導入

0.1

演算子注釈

Update 12

本体の実装

必要

性能特性

Extract

入力数

1

出力数

1

ビュー引数

指定可能

値引数

指定可能

型引数

指定可能

更新演算子の入出力

分類

名前

単位

型

備考

入力

in

レコード

任意

出力

out

レコード

inと同様

12

com.asakusafw.vocabulary.operator.Update [https://docs.asakusafw.com/0.10.3/release/api/com/asakusafw/vocabulary/operator/Update.html]

更新演算子の実装

更新演算子の演算子メソッドには次のような情報を指定します。

更新演算子の実装

分類

対応

型

キー

備考

返戻

なし

void

不可

引数1

入出力

モデル

不可

ビュー引数

入力

ビュー

任意

値引数

なし

プリミティブ

不可

この演算子は、単一の入力に流れるデータの項目を変更し、出力に流します。

対象のメソッドは一つの引数を取り、メソッドの本体で引数の内容を変更するプログラムを記述します。メソッド内で引数のデータモデルオブジェクトを破壊的に変更すると、変更結果が演算子の出力になります。

引数には同メソッドで宣言した型変数を利用できます。

更新演算子の演算子メソッドは、一般的な演算子メソッドの要件の他に、 下記の要件をすべて満たす必要があります。

返戻型にvoidを指定する

以下の引数を宣言する

データモデルオブジェクト型の引数

以下の修飾子を付与する

(特になし)

以下の修飾子は付与しない

abstract

以下は実装例です。

/**
 * レコードの値に100を設定する。
 * @param hoge 更新するレコード
 */
@Update
public void edit(Hoge hoge) {
    hoge.setValue(100);
}

変換演算子

レコードを別の型のレコードに変換する演算子です。主に「レコードから別のレコードを作成する」という目的で利用します。

変換演算子の概要

項目

説明

分類

ユーザー

導入

0.1

演算子注釈

Convert 13

本体の実装

必要

性能特性

Extract

入力数

1

出力数

2

ビュー引数

指定可能

値引数

指定可能

型引数

指定可能

変換演算子の入出力

分類

名前

単位

型

備考

入力

in

レコード

任意

出力

out

レコード

任意

変換後のデータ

出力

original

レコード

inと同様

変換前のデータ

13

com.asakusafw.vocabulary.operator.Convert [https://docs.asakusafw.com/0.10.3/release/api/com/asakusafw/vocabulary/operator/Convert.html]

Hint

レコードから不要なプロパティを除去したり、新たなプロパティを追加する場合は 射影演算子 や 拡張演算子 、 再構築演算子 の利用を推奨しています。

変換演算子の実装

変換演算子の演算子メソッドには次のような情報を指定します。

変換演算子の実装

分類

対応

型

キー

備考

返戻

出力

モデル

不可

型引数は指定不可

引数1

入力

モデル

不可

ビュー引数

入力

ビュー

任意

値引数

なし

プリミティブ

不可

この演算子は、入力されたデータを他の種類のデータに変換し、出力に流します。

一つの引数を取り、変換して別のデータモデルオブジェクトを返すプログラムを記述します。メソッドから返したデータモデルオブジェクトが演算子の出力になります。このデータモデルオブジェクトは、演算子クラスと一緒に一度だけインスタンス化して再利用することが可能です。

この演算子をフロー部品やジョブフローで使用する際に、出力 original は他の演算子等と結線されていなくてもエラーにならない、という特性を持ちます。ただし、Asakusa on MapReduce 利用時には original の結線を省略することはできません。

引数には同メソッドで宣言した型変数を利用できますが、 戻り値の型に型変数を含めることはできません。

変換演算子の演算子メソッドは、一般的な演算子メソッドの要件の他に、 下記の要件をすべて満たす必要があります。

返戻型に変換後のデータモデルオブジェクト型を指定する

以下の引数を宣言する

データモデルオブジェクト型の引数

以下の修飾子を付与する

(特になし)

以下の修飾子は付与しない

abstract

このフレームワークを正しく利用する限り、この注釈を付与するメソッドはスレッド安全となります。ただし、同メソッドが共有データを操作したり、または共有データを操作する別のメソッドを起動したりする場合についてはスレッド安全ではありません。

以下は実装例です。

// スレッド安全なので変換後のオブジェクトは再利用可能
private final Foo foo = new Foo();

/**
 * レコードHogeを等価なFooに変換して返す。
 * @param hoge 変換するレコード
 * @return 変換後のレコード
 */
@Convert
public Foo toFoo(Hoge hoge) {
    foo.setValue(hoge.getValue());
    return foo;
}

拡張演算子

レコードに新たなプロパティを追加した別の型に変換する演算子です。計算のために一時的にプロパティを追加したい場合などに利用することを想定しています。

拡張演算子の概要

項目

説明

分類

コア

導入

0.2

メソッド

extend

性能特性

Extract

入力数

1

出力数

1

拡張演算子の入出力

分類

名前

単位

型

備考

入力

in

レコード

任意

出力

out

レコード

任意

入出力の型に制約あり

Attention

拡張演算子を利用する場合、変換後のレコードには変換前の型にある全てのプロパティが定義されている必要があります。つまり、この演算子は「プロパティを増やす」場合のみに利用できます。

拡張演算子の実装

拡張演算子はコア演算子に分類されるため、Operator DSLでの実装はありません。 Flow DSLからは次のように利用します。

In<Hoge> in;
Out<Foo> out;

@Override
protected void describe() {
    CoreOperatorFactory core = new CoreOperatorFactory();
    Extend<Foo> op = core.extend(in, Foo.class);
    out.add(op);
}

上記の例では、 Hoge が持つすべてのプロパティを Foo も持っていなければなりません。そうでない場合、コンパイル時にエラーとなります。

射影演算子

レコードから不要なプロパティを除去した別の型に変換する演算子です。計算のために一時的に導入していたプロパティなどを除去したり、出力前に適切な型に変換することを想定としています。

射影演算子の概要

項目

説明

分類

コア

導入

0.2

メソッド

project

性能特性

Extract

入力数

1

出力数

1

射影演算子の入出力

分類

名前

単位

型

備考

入力

in

レコード

任意

出力

out

レコード

任意

入出力の型に制約あり

Attention

射影演算子を利用する場合、変換前の型には変換後のレコードにある全てのプロパティが定義されている必要があります。つまり、この演算子は「プロパティを減らす」場合のみに利用できます。

射影演算子の実装

射影演算子はコア演算子に分類されるため、Operator DSLでの実装はありません。 Flow DSLからは次のように利用します。

In<Foo> in;
Out<Hoge> out;

@Override
protected void describe() {
    CoreOperatorFactory core = new CoreOperatorFactory();
    Project<Hoge> op = core.project(in, Hoge.class);
    out.add(op);
}

上記の例では、 Hoge が持つすべてのプロパティを Foo も持っていなければなりません。そうでない場合、コンパイル時にエラーとなります。

再構築演算子

レコードの内容を別の型に移し替える演算子です。元の型と移し替える先の型のうち、両者に共通するプロパティのみをコピーします。

再構築演算子の概要

項目

説明

分類

コア

導入

0.2.1

メソッド

restructure

性能特性

Extract

入力数

1

出力数

1

再構築演算子の入出力

分類

名前

単位

型

備考

入力

in

レコード

任意

出力

out

レコード

任意

Hint

再構築演算子は、 拡張演算子 や 射影演算子 の制約を緩めたものです。これらの演算子が利用できる場面では通常再構築演算子も利用できますが、データ構造がむやみに変更された際にコンパイラによるチェックが甘くなります。拡張演算子や射影演算子で十分である場合、できるだけそちらを利用することを推奨します。

再構築演算子の実装

再構築演算子はコア演算子に分類されるため、Operator DSLでの実装はありません。 Flow DSLからは次のように利用します。

In<Foo> in;
Out<Hoge> out;

@Override
protected void describe() {
    CoreOperatorFactory core = new CoreOperatorFactory();
    Restructure<Hoge> op = core.restructure(in, Hoge.class);
    out.add(op);
}

上記の例では、 Hoge と Foo に共通するプロパティのみが、 Hoge ( in ) から Foo にコピーされます。

抽出演算子

レコードに含まれるデータを抽出して、複数のレコードを生成する演算子です。主に「レコードを分解して別のレコードを作成する」という目的で利用します。

抽出演算子の概要

項目

説明

分類

ユーザー

導入

0.2.1

演算子注釈

Extract 14

本体の実装

必要

性能特性

Extract

入力数

1

出力数

任意

ビュー引数

指定可能

値引数

指定可能

型引数

指定可能

抽出演算子の入出力

分類

名前

単位

型

備考

入力

in

レコード

任意

出力

(任意)

レコード

任意

任意個数を指定可

14

com.asakusafw.vocabulary.operator.Extract [https://docs.asakusafw.com/0.10.3/release/api/com/asakusafw/vocabulary/operator/Extract.html]

抽出演算子の実装

抽出演算子の演算子メソッドには次のような情報を指定します。

抽出演算子の実装

分類

対応

型

キー

備考

返戻

出力

void

不可

引数1

入力

モデル

不可

ビュー引数

入力

ビュー

任意

以降の引数

各出力

結果

不可

任意の個数

値引数

なし

プリミティブ

不可

この演算子は、入力されたデータから任意のデータを抽出し、それぞれ出力に流します。

一つのデータモデルオブジェクト型の引数と、 複数の結果オブジェクト型の引数を取り、引数から抽出した任意のデータモデルオブジェクトを結果オブジェクトに出力を行うプログラムを記述します。

出力は任意個の結果で、メソッド内で同じ結果に対して複数回の結果を指定することも可能です。

引数には同メソッドで宣言した型変数を利用できますが、全ての結果オブジェクト型の出力に型変数を含める場合には、入力に同様の型変数を指定してある必要があります。

抽出演算子の演算子メソッドは、一般的な演算子メソッドの要件の他に、 下記の要件をすべて満たす必要があります。

返戻型にvoidを指定する

以下の引数を宣言する

データモデルオブジェクト型の引数

一つ以上の結果型の引数

以下の修飾子を付与する

(特になし)

以下の修飾子は付与しない

abstract

以下は実装例です。

// スレッド安全なので抽出結果のオブジェクトは再利用可能
private final A a = new A();
private final B b = new B();

/**
 * レコードに含まれるそれぞれのフィールドを抽出し、出力する。
 * @param hoge 抽出対象のデータモデル
 * @param aResult aの抽出結果
 * @param bResult bの抽出結果
 */
@Extract
public void extractFields(
        Hoge hoge,
        Result<A> aResult,
        Result<B> bResult) {
    a.setValue(hoge.getA());
    aResult.add(a);
    b.setValue(hoge.getB0());
    bResult.add(b);
    b.setValue(hoge.getB1());
    bResult.add(b);
}

結合演算子

結合系の演算子は、複数のレコードを突き合わせたり結合したりするための演算子です。

マスタ確認演算子

レコードと同様のキーを持つレコードを別の入力から探し、存在する場合としない場合で出力を振り分ける演算子です。

マスタ確認演算子の概要

項目

説明

分類

ユーザー

導入

0.1

演算子注釈

MasterCheck 15

本体の実装

不要

性能特性

Join

入力数

2

出力数

2

ビュー引数

指定可能

値引数

指定可能

型引数

指定可能

備考

マスタ選択を利用可能

マスタ確認演算子の入出力

分類

名前

単位

型

備考

入力

master

グループ

任意

グループ化を指定

入力

tx

レコード

任意

グループ化を指定

出力

found

レコード

txと同様

マスタが見つかったもの

出力

missed

レコード

txと同様

マスタが見つからなかったもの

15

com.asakusafw.vocabulary.operator.MasterCheck [https://docs.asakusafw.com/0.10.3/release/api/com/asakusafw/vocabulary/operator/MasterCheck.html]

マスタ確認演算子の実装

マスタ確認演算子の演算子メソッドには次のような情報を指定します。

マスタ確認演算子の実装

分類

対応

型

キー

備考

返戻

出力

boolean

不可

引数1

入力

モデル

必須

マスタデータの入力

引数2

入力

モデル

必須

ビュー引数

入力

ビュー

任意

値引数

なし

プリミティブ

不可

この演算子は、トランザクションデータに対応するマスタデータを引き当てて確認し、マスタデータを発見できたものと発見できなかったものに分けて出力に流します。

このメソッドには本体を指定せず、抽象メソッドとして宣言します。

対象のメソッドは結合対象の二つのデータモデルオブジェクト型の引数を取ります。このとき最初の引数は、マスタデータなど結合条件に対してユニークであるようなデータモデルオブジェクトである必要があります。

戻り値型にはboolean型を指定します。マスタデータを発見できた場合は ture 、 発見できなかった場合は false を返却します。

データモデルオブジェクト型の引数にはそれぞれ Key 注釈を指定し、 group でグループ化のためのプロパティ名を指定します。それぞれのプロパティ列が完全に一致するものが結合対象になります。整列のためのプロパティ名および整列方向に関する動作は規定されません。

引数には同メソッドで宣言した型変数を利用できます。

マスタ確認演算子の演算子メソッドは、一般的な演算子メソッドの要件の他に、 下記の要件をすべて満たす必要があります。

返戻型にboolean型を指定する

以下の引数を宣言する

結合対象のデータモデルオブジェクト型の引数 (マスタデータ)、さらに Key 注釈でグループ化のための情報を指定する

結合対象のデータモデルオブジェクト型の引数、さらに Key 注釈でグループ化のための情報を指定する

以下の修飾子を付与する

abstract

以下の修飾子は付与しない

(特になし)

以下は実装例です。

/**
 * レコードHogeTrnに対するHogeMstが存在する場合に{@code true}を返す。
 * @param master マスタデータ
 * @param tx トランザクションデータ
 * @return HogeMstが存在する場合のみtrue
 */
@MasterCheck
public abstract boolean exists(
        @Key(group = "id") HogeMst master,
        @Key(group = "masterId") HogeTrn tx);

また、この演算子注釈に selection を指定することで、非等価結合条件を記述することも可能です。詳しくは マスタ選択 を参照して下さい。

マスタ結合演算子

レコードと同様のキーを持つレコードを別の入力から探し、それらを結合したレコードを出力する演算子です。この演算子は、結合モデル 16 のレコードを構築します。

入力はそれぞれ結合モデルの元になったデータモデルを指定し、結合に成功した場合に結合モデルが出力され、失敗した場合には元になったレコードが出力されます。

また、結合条件や結合方法は結合モデルに指定したものを利用します。

マスタ結合演算子の概要

項目

説明

分類

ユーザー

導入

0.1

演算子注釈

MasterJoin 17

本体の実装

不要

性能特性

Join

入力数

2

出力数

2

ビュー引数

指定可能

値引数

指定可能

型引数

指定不可

備考

マスタ選択を利用可能

マスタ結合演算子の入出力

分類

名前

単位

型

備考

入力

master

グループ

任意

入力

tx

レコード

任意

出力

joined

レコード

任意

結合結果、結合モデルを指定

出力

missed

レコード

txと同様

マスタが見つからなかったもの

16

結合モデルについては DMDLユーザーガイド を参照してください。

17

com.asakusafw.vocabulary.operator.MasterJoin [https://docs.asakusafw.com/0.10.3/release/api/com/asakusafw/vocabulary/operator/MasterJoin.html]

マスタ結合演算子の実装

マスタ結合演算子の演算子メソッドには次のような情報を指定します。

マスタ結合演算子の実装

分類

対応

型

キー

備考

返戻

出力

モデル

不可

結合モデルのみ

引数1

入力

モデル

不可

マスタデータの入力

引数2

入力

モデル

不可

ビュー引数

入力

ビュー

任意

値引数

なし

プリミティブ

不可

この演算子は、トランザクションデータに対して対応するマスタデータを結合し、結合結果のレコードを出力に流します。

このメソッドには本体を指定せず、抽象メソッドとして宣言します。

対象のメソッドは、結合対象の二つのデータモデルオブジェクト型の引数を取ります。このとき最初の引数は、マスタデータなど結合条件に対してユニークであるようなデータモデルオブジェクトである必要があります。

戻り値型には結合結果を表す結合モデルの型を指定します。結合モデルの型は、必ず結合対象の二つのデータモデルオブジェクトを結合したものである必要があります。

この演算子の結合条件や結合方法は、結合モデル型の注釈 18 に全て埋め込まれています。そのため、他のマスタ操作系の演算子とは異なり、 Key の指定は不要です。

この演算子メソッドには型引数を定義できません。

マスタ結合演算子の演算子メソッドは、一般的な演算子メソッドの要件の他に、 下記の要件をすべて満たす必要があります。

返戻型に結合結果となるモデル型を指定する

以下の引数を宣言する

結合対象のデータモデルオブジェクト型の引数 (マスタデータ)

結合対象のデータモデルオブジェクト型の引数

以下の修飾子を付与する

abstract

以下の修飾子は付与しない

(特になし)

以下は実装例です。

/**
 * レコードHogeMstとHogeTrnを結合し、結合結果のHogeを返す。
 * @param master マスタデータ
 * @param tx トランザクションデータ
 * @return 結合結果
 */
@MasterJoin
public abstract Hoge join(HogeMst master, HogeTrn tx);

また、この演算子注釈に selection を指定することで、非等価結合条件を記述することも可能です。詳しくは マスタ選択 を参照して下さい。

18

com.asakusafw.vocabulary.model.Joined [https://docs.asakusafw.com/0.10.3/release/api/com/asakusafw/vocabulary/model/Joined.html]

マスタ分岐演算子

レコードと同様のキーを持つレコードを別の入力から探し、両方の情報を元にそれぞれの出力にレコードを振り分ける演算子です。この演算子は、マスタを引き当てつつ 分岐演算子 と同等の処理を行います。

マスタ分岐演算子の概要

項目

説明

分類

ユーザー

導入

0.1

演算子注釈

MasterBranch 19

本体の実装

必要

性能特性

Join

入力数

2

出力数

任意

ビュー引数

指定可能

値引数

指定可能

型引数

指定可能

備考

マスタ選択を利用可能

マスタ分岐の入出力

分類

名前

単位

型

備考

入力

master

グループ

任意

グループ化を指定

入力

tx

レコード

任意

グループ化を指定

出力

(任意)

レコード

txと同様

任意の個数を指定可

19

com.asakusafw.vocabulary.operator.MasterBranch [https://docs.asakusafw.com/0.10.3/release/api/com/asakusafw/vocabulary/operator/MasterBranch.html]

マスタ分岐演算子の実装

マスタ分岐演算子の演算子メソッドには次のような情報を指定します。

マスタ分岐演算子の実装

分類

対応

型

キー

備考

返戻

全出力

列挙型

不可

列挙定数ごとに出力

引数1

入力

モデル

必須

マスタデータの入力

引数2

入力

モデル

必須

ビュー引数

入力

ビュー

任意

値引数

なし

プリミティブ

不可

この演算子は、トランザクションデータに対応するマスタデータを引き当て、それらの内容に応じてトランザクションデータをそれぞれの出力に振り分けます。

対象のメソッドは結合対象の二つのデータモデルオブジェクト型の引数を取ります。このとき最初の引数は、マスタデータなど結合条件に対してユニークであるようなデータモデルオブジェクトである必要があります。

戻り値型には、分岐先を表現する列挙定数を返します。この列挙型は、分岐先の出力名を表しています。メソッドから列挙定数を返すと、その時点の引数に渡された入力が、返した列挙定数に対応する出力に渡されます。

データモデルオブジェクト型の引数にはそれぞれ Key 注釈を指定し、 group でグループ化のためのプロパティ名を指定します。それぞれのプロパティ列が完全に一致するものが結合対象になります。整列のためのプロパティ名および整列方向に関する動作は規定されません。

引数には同メソッドで宣言した型変数を利用できます。

マスタ分岐演算子の演算子メソッドは、一般的な演算子メソッドの要件の他に、 下記の要件をすべて満たす必要があります。

返戻型には分岐先を表現する列挙型を指定する

その列挙型は、public として宣言されている

その列挙型は、一つ以上の列挙定数を持つ

以下の引数を宣言する

結合対象のデータモデルオブジェクト型の引数 (マスタデータ)、さらに Key 注釈でグループ化のための情報を指定する

結合対象のデータモデルオブジェクト型の引数、さらに Key 注釈でグループ化のための情報を指定する

以下の修飾子を付与する

(特になし)

以下の修飾子は付与しない

abstract

Attention

マスタ分岐演算子の内部では、入力の内容を変更しないようにしてください。そのような動作を期待する場合、 マスタつき更新演算子 と 分岐演算子 を組み合わせて利用するようにしてください。

Attention

この演算子の引数1 (マスタデータの入力) には、引き当てるマスタが見つからなかった場合に null が渡されます。これは他のマスタ系の演算子とは異なる動作ですので、注意が必要です。

以下は実装例です。

public abstract class OperatorClass {
    ...

    /**
     * レコードの状態ごとに処理を分岐する。
     * @param master マスタデータ、存在しない場合は{@code null}
     * @param tx トランザクションデータ
     * @return 分岐先を表すオブジェクト
     */
    @MasterBranch
    public Status branchWithJoin(
            @Key(group = "id") ItemMst master,
            @Key(group = "itemId") HogeTrn tx) {
        if (master == null) {
            return Status.ERROR;
        }
        int price = master.getPrice();
        if (price < 0) {
            return Status.ERROR;
        }
        if (price >= 1000000) {
            return Status.EXPENSIVE;
        }
        return Status.CHEAP;
    }

    /**
     * 値段に関するレコードの状態。
     */
    public enum Status {
        /**
         * 高い。
         */
        EXPENSIVE,

        /**
         * 安い。
         */
        CHEAP,

        /**
         * エラー。
         */
        ERROR,
    }

    ...
}

また、この演算子注釈に selection を指定することで、非等価結合条件を記述することも可能です。詳しくは マスタ選択 を参照して下さい。

マスタつき更新演算子

レコードと同様のキーを持つレコードを別の入力から探し、両方の情報を元に片方のレコードの内容を更新する演算子です。この演算子は、マスタを引き当てつつ 更新演算子 と同等の処理を行います。

マスタつき更新演算子の概要

項目

説明

分類

ユーザー

導入

0.1

演算子注釈

MasterJoinUpdate 20

本体の実装

必要

性能特性

Join

入力数

2

出力数

2

ビュー引数

指定可能

値引数

指定可能

型引数

指定可能

備考

マスタ選択を利用可能

マスタつき更新演算子の入出力

分類

名前

単位

型

備考

入力

master

グループ

任意

グループ化を指定

入力

tx

レコード

任意

グループ化を指定

出力

updated

レコード

txと同様

マスタが見つかったもの

出力

missed

レコード

txと同様

マスタが見つからなかったもの

20

com.asakusafw.vocabulary.operator.MasterJoinUpdate [https://docs.asakusafw.com/0.10.3/release/api/com/asakusafw/vocabulary/operator/MasterJoinUpdate.html]

マスタつき更新演算子の実装

マスタつき更新演算子の演算子メソッドには次のような情報を指定します。

マスタつき更新演算子の実装

分類

対応

型

キー

備考

返戻

出力

void

不可

引数1

入力

モデル

必須

マスタデータの入力

引数2

入力

モデル

必須

変更対象のデータ

ビュー引数

入力

ビュー

任意

値引数

なし

プリミティブ

不可

この演算子は、トランザクションデータに対応するマスタデータを引き当てたのち、マスタデータの情報を利用してトランザクションデータの任意の項目を変更し、出力に流します。

対象のメソッドは結合対象の二つのデータモデルオブジェクト型の引数を取ります。このとき最初の引数は、マスタデータなど結合条件に対してユニークであるようなデータモデルオブジェクトである必要があります。

データモデルオブジェクト型の引数にはそれぞれ Key 注釈を指定し、 group でグループ化のためのプロパティ名を指定します。それぞれのプロパティ列が完全に一致するものが結合対象になります。整列のためのプロパティ名および整列方向に関する動作は規定されません。

メソッドの本体では、引数のトランザクションデータの内容を変更するプログラムを記述します。マスタデータの内容を変更した際の動作は規定されません。

引数には同メソッドで宣言した型変数を利用できますが、全ての結果オブジェクト型の出力に型変数を含める場合には、いずれかの入力に同様の型変数を指定してある必要があります。

マスタつき更新演算子の演算子メソッドは、一般的な演算子メソッドの要件の他に、 下記の要件をすべて満たす必要があります。

返戻型にvoidを指定する

以下の引数を宣言する

結合対象のデータモデルオブジェクト型の引数 (マスタデータ)、さらに Key 注釈でグループ化のための情報を指定する

結合対象のデータモデルオブジェクト型の引数、さらに Key 注釈でグループ化のための情報を指定する

以下の修飾子を付与する

(特になし)

以下の修飾子は付与しない

abstract

以下は実装例です。

/**
 * マスタの価格をトランザクションデータに設定する。
 * @param master マスタデータ
 * @param tx 変更するトランザクションデータ
 */
@MasterJoinUpdate
public void updateWithMaster(
        @Key(group = "id") ItemMst master,
        @Key(group = "itemId") HogeTrn tx) {
    tx.setPrice(master.getPrice());
}

また、この演算子注釈に selection を指定することで、非等価結合条件を記述することも可能です。詳しくは マスタ選択 を参照して下さい。

グループ結合演算子

複数の入力をキーでグループ化し、キーが一致する入力ごとのグループをまとめて操作する演算子です。非常に複雑な操作を表現できますが、コンパイラの最適化を適用しにくかったり、グループごとの大きさに制限があるなどの問題もあります。

グループ結合演算子の概要

項目

説明

分類

ユーザー

導入

0.1

演算子注釈

CoGroup 21

本体の実装

必要

性能特性

CoGroup

入力数

任意

出力数

任意

ビュー引数

指定可能

値引数

指定可能

型引数

指定可能

備考

グループ結合演算子の入出力

分類

名前

単位

型

備考

入力

(任意)

グループ

任意

任意の個数、グループ化を指定

出力

(任意)

レコード

任意

任意の個数

21

com.asakusafw.vocabulary.operator.CoGroup [https://docs.asakusafw.com/0.10.3/release/api/com/asakusafw/vocabulary/operator/CoGroup.html]

グループ結合演算子の実装

グループ結合演算子の演算子メソッドには次のような情報を指定します。

グループ結合演算子の実装

分類

対応

型

キー

備考

返戻

出力

void

不可

引数1～

各入力

リスト

必須

任意の個数

ビュー引数

入力

ビュー

任意

以降の引数

各出力

結果

不可

任意の個数

値引数

なし

プリミティブ

不可

この演算子は、2種類以上のデータをそれぞれ条件に応じてグループ化してリストを作成し、 それらのリストを処理した結果を出力します。

入力は任意個のリストで、それぞれに Key 注釈のグループ化条件 group でプロパティの一覧を指定し、プロパティ列が完全に一致するものごとにメソッド内の処理を行います。いくつかのグループに要素が存在しない場合、対応する引数には要素数0のリストが渡されます。

なお、 Key 注釈の整列条件 order でプロパティの一覧を指定すると、対象のリストの各要素は指定されたプロパティの内容で整列されます。

出力は任意個の結果で、メソッド内で同じ結果に対して複数回の結果を指定することも可能です。結果の要素型には型引数の指定が可能ですが、その型引数は入力でも利用されている必要があります。

グループ結合演算子の演算子メソッドは、一般的な演算子メソッドの要件の他に、 下記の要件をすべて満たす必要があります。

返戻型にvoidを指定する

以下の引数を宣言する

一つ以上のデータモデルオブジェクトを要素に取るリスト型の引数、 さらにそれぞれ Key 注釈でグループ化と整列のための情報を指定する

一つ以上の結果型の引数

以下の修飾子を付与する

(特になし)

以下の修飾子は付与しない

abstract

以下は実装例です。

/**
 * HogeとFooをHogeのIDでグループ化し、重複なしで突合できたもののみを結果として出力する。
 * それ以外の値はエラーとして出力する。
 * @param hogeList Hogeのグループごとのリスト
 * @param fooList Fooのグループごとのリスト
 * @param hogeResult 成功したHoge
 * @param fooResult 成功したFoo
 * @param hogeError 失敗したHoge
 * @param fooError 失敗したFoo
 */
@CoGroup
public void checkUp(
        @Key(group = "id") List<Hoge> hogeList,
        @Key(group = "hogeId") List<Foo> fooList,
        Result<Hoge> hogeResult,
        Result<Foo> fooResult,
        Result<Hoge> hogeError,
        Result<Foo> fooError) {
    // いずれも存在＋重複なしで突合成功
    if (hogeList.size() == 1 && fooList.size() == 1) {
        hogeResult.add(hogeList.get(0));
        fooResult.add(fooList.get(0));
    }
    // それ以外はエラー
    else {
        for (Hoge hoge : hogeList) {
            hogeError.add(hoge);
        }
        for (Foo foo : fooList) {
            fooError.add(foo);
        }
    }
}

巨大な入力グループへの対応

グループ結合演算子の実装 において、演算子の入力には List を指定しています。この演算子は基本的に小さなグループごとに処理することを想定しており、大きなグループを処理する場合に List 内の要素が多くなりすぎて、メモリが不足してしまう場合があります。

これを回避するために、演算子メソッドの各入力の引数に @Once注釈 、または @Spill注釈 を指定することができます。

Attention

Asakusa on MapReduce では @Once 注釈 および @Spill 注釈を利用できません。 Asakusa on MapReduce では後述の InputBuffer.ESCAPE に記載の方法を利用してください。

@Once注釈

@Once 22 注釈を演算子の入力に指定すると、メモリ消費を抑え大きな入力グループを安全に取り扱うことができます。ただし、入力には以下の制約が課せられます。

引数の型は Iterable<...> でなければならない (通常は List<...> )

各要素の内容は一度だけしか読み出せない

以下は @Once 注釈を使用するグループ結合演算子メソッドの例です。演算子メソッドの各入力に @Once 注釈を付与し、引数の型を List から Iterable に変更しています。

@CoGroup
public void cogroupWithOnce(
        @Key(group = "hogeCode") @Once Iterable<Hoge> hogeList,
        @Key(group = "hogeId") @Once Iterable<Foo> fooList,
        Result<Hoge> hogeResult,
        Result<Foo> fooResult
        ) {
    for (Hoge hoge : hogeList) {
        ...
    }
    for (Foo foo : fooList) {
        ...
    }
}

22

com.asakusafw.vocabulary.model.Once [https://docs.asakusafw.com/0.10.3/release/api/com/asakusafw/vocabulary/model/Once.html]

@Spill注釈

@Spill 23 注釈を演算子の入力に指定すると、演算子メソッドの引数に指定したリストはメモリ外のストレージを一時的に利用します。 Java VMのヒープ上に配置されるオブジェクトは全体の一部で、残りはファイルシステム上などの領域に保存します。

これにより List を利用しつつ巨大な入力データを取り扱えるようになります。また、 @Once 注釈では制約のある、リストに対する複数回アクセスやランダムアクセスが可能です。

Attention

@Spill 注釈を利用するとほとんどの場合に著しくパフォーマンスが低下します。また、一時領域のストレージ構成や空き領域の確保といった、環境面での考慮も必要になります。

このため、通常は @Once 注釈の利用を推奨します。演算子メソッド実装の都合上 @Once 注釈の制約が許容できない場合にのみ、 @Spill 注釈の利用を検討してください。

@Spill 注釈を指定した入力の List には以下に示す多大な制約がかかります。

それぞれの List からはひとつずつしかオブジェクトを取り出せなくなる。

2つ以上オブジェクトを取り出した場合、最後に取り出したオブジェクト以外はまったく別の内容に変更されている可能性がある。

リストから取り出したオブジェクトを変更しても、リストの別の要素にアクセスしただけで変更したオブジェクトの内容が失われる可能性がある。

つまり、次のようなプログラムを書いた場合の動作は保証されません。

@CoGroup
public void invalid(@Key(group = "id") @Spill List<Hoge> list, Result<Hoge> result) {
    // 二つ取り出すとaの内容が保証されない
    Hoge a = list.get(0);
    Hoge b = list.get(1);

    // 内容を変更しても、別の要素を参照しただけでオブジェクトの内容が変わる場合がある
    b.setValue(100);
    list.get(2);
}

上記のようなプログラムを書きたい場合、かならずオブジェクトのコピーを作成してください。

Hoge a = new Hoge();
Hoge b = new Hoge();

@CoGroup
public void valid(@Key(group = "id") @Spill List<Hoge> list, Result<Hoge> result) {
    a.copyFrom(list.get(0));
    b.copyFrom(list.get(1));
    b.setValue(100);
    list.get(2);
    ...
}

なお、下記のようにひとつずつ取り出して使う場合、オブジェクトをコピーする必要はありません（ただし、このケースでは @Once で代替可能です）。

@CoGroup
public void valid(@Key(group = "id") @Spill List<Hoge> list, Result<Hoge> result) {
    for (Hoge hoge : list) {
        hoge.setValue(100);
        result.add(hoge);
    }
}

23

com.asakusafw.vocabulary.model.Spill [https://docs.asakusafw.com/0.10.3/release/api/com/asakusafw/vocabulary/model/Spill.html]

InputBuffer.ESCAPE

Attention

バージョン 0.10.3 において、 InputBuffer.ESCAPE を指定する方法は過去バージョンとの互換性維持のため提供していますが、将来のバージョンでは非推奨となる予定です。 Asakusa on Spark、および Asakusa on M³BP ではこの機能の代わりに @Once注釈 および @Spill注釈 の利用を推奨します。

グループ結合演算子の実装 において、演算子の入力には List を指定しています。この演算子は基本的に小さなグループごとに処理することを想定しており、大きなグループを処理する場合に List 内の要素が多くなりすぎて、メモリが不足してしまう場合があります。

これを回避するには、演算子注釈の要素 inputBuffer に InputBuffer.ESCAPE 24 を指定します。何も指定しない場合は、ヒープ上に全てのデータを保持する InputBuffer.EXPAND が利用されます。

InputBuffer.ESCAPE を指定した場合、巨大な入力データを取り扱えるようになる代わりに、演算子メソッドの引数に指定した List に以下に示す多大な制約がかかります。

それぞれの List からはひとつずつしかオブジェクトを取り出せなくなる。

2つ以上オブジェクトを取り出した場合、最後に取り出したオブジェクト以外はまったく別の内容に変更されている可能性がある。

リストから取り出したオブジェクトを変更しても、リストの別の要素にアクセスしただけで変更したオブジェクトの内容が失われる可能性がある。

Warning

ESCAPE を指定した場合、メモリ外のストレージを一時的に利用します。そのため、ほとんどの場合に著しくパフォーマンスが低下します。

Note

ESCAPE を指定すると、演算子メソッドの引数に指定したリストは 内部的に「スワップ領域」を裏側に持ちます。 Java VMのヒープ上に配置されるオブジェクトは全体の一部で、残りはファイルシステム上などの領域に保存します。ヒープ上には常に同じオブジェクトを利用して、スワップから復帰するときはそれらのオブジェクトを再利用しています。この制約は、今後解消されるかもしれません。

つまり、次のようなプログラムを書いた場合の動作は保証されません。

@CoGroup(inputBuffer = InputBuffer.ESCAPE)
public void invalid(@Key(group = "id") List<Hoge> list, Result<Hoge> result) {
    // 二つ取り出すとaの内容が保証されない
    Hoge a = list.get(0);
    Hoge b = list.get(1);

    // 内容を変更しても、別の要素を参照しただけでオブジェクトの内容が変わる場合がある
    b.setValue(100);
    list.get(2);
}

上記のようなプログラムを書きたい場合、かならずオブジェクトのコピーを作成してください。

Hoge a = new Hoge();
Hoge b = new Hoge();

@CoGroup(inputBuffer = InputBuffer.ESCAPE)
public void valid(@Key(group = "id") List<Hoge> list, Result<Hoge> result) {
    a.copyFrom(list.get(0));
    b.copyFrom(list.get(1));
    b.setValue(100);
    list.get(2);
    ...
}

なお、下記のようにひとつずつ取り出して使う場合、オブジェクトをコピーする必要はありません。

@CoGroup(inputBuffer = InputBuffer.ESCAPE)
public void valid(List<Hoge> list, Result<Hoge> result) {
    for (Hoge hoge : list) {
        hoge.setValue(100);
        result.add(hoge);
    }
}

24

com.asakusafw.vocabulary.flow.processor.InputBuffer [https://docs.asakusafw.com/0.10.3/release/api/com/asakusafw/vocabulary/flow/processor/InputBuffer.html]

分割演算子

結合モデルから結合元のレコードを抽出してそれぞれ出力する演算子です。この演算子への入力は、結合モデルである必要があります。

分割演算子の概要

項目

説明

分類

ユーザー

導入

0.1

演算子注釈

Split 25

本体の実装

不要

性能特性

Extract

入力数

1

出力数

2

ビュー引数

指定不可

値引数

指定不可

型引数

指定不可

備考

分割演算子の入出力

分類

名前

単位

型

備考

入力

in

レコード

任意

結合モデルのみ

出力

left

レコード

特殊

結合モデルの左項の型

出力

right

レコード

特殊

結合モデルの右項の型

25

com.asakusafw.vocabulary.operator.Split [https://docs.asakusafw.com/0.10.3/release/api/com/asakusafw/vocabulary/operator/Split.html]

分割演算子の実装

分割演算子の演算子メソッドには次のような情報を指定します。

分割演算子の実装

分類

対応

型

キー

備考

返戻

なし

void

不可

引数1

入力

モデル

不可

結合モデル

引数2

出力

結果

不可

結合モデルの元になったモデル

引数3

出力

結果

不可

結合モデルの元になったモデル

この演算子は、結合済みのデータを入力に取り、結合前のデータに分割してそれぞれ出力します。

このメソッドには本体を指定せず、抽象メソッドとして宣言します。

対象のメソッドは一つのデータモデルオブジェクト型の引数と、二つの結果オブジェクトの引数を取ります。このメソッドは結合データモデルオブジェクトの結合情報を元に、結合前のデータモデルオブジェクトをそれぞれ返すようなプログラムを自動的に生成します。

引数1には分割したい対象の結合モデルの型を指定します。以降の引数には、分割結果を表す結果型を指定します。この分割結果は、分割対象の結合モデルの元になったデータモデル型である必要があります。

この演算子メソッドには型引数を定義できません。

分割演算子の演算子メソッドは、一般的な演算子メソッドの要件の他に、 下記の要件をすべて満たす必要があります。

返戻型にvoidを指定する

以下の引数を宣言する

結合済みのデータモデルオブジェクト型の引数

Result 型の型引数に、一つ目の分割先のデータモデルオブジェクト型を指定した引数

Result 型の型引数に、二つ目の分割先のデータモデルオブジェクト型を指定した引数

以下の修飾子を付与する

abstract

以下の修飾子は付与しない

(特になし)

以下は実装例です。

/**
 * レコードHogeFooをHogeとFooに分割する。
 * @param joined 分割するレコード
 * @param hoge 分割後のHoge
 * @param foo 分割後のFoo
 */
@Split
public abstract void split(
        HogeFoo joined,
        Result<Hoge> hoge,
        Result<Foo> foo);

集計演算子

集計系の演算子は、主にグループ化したレコード内での計算を行うための演算子です。

単純集計演算子

レコードをキーでグループ化し、グループ内で集計した結果を出力する演算子です。この演算子は、集計モデル 26 のレコードを構築します。入力は集計モデルの元になったデータモデルを指定し、集計結果の集計モデルが出力されます。また、グループ化条件や集計方法は集計モデルに指定したものを利用します。

単純集計演算子の概要

項目

説明

分類

ユーザー

導入

0.1

演算子注釈

Summarize 27

本体の実装

不要

性能特性

Fold

入力数

1

出力数

1

ビュー引数

指定不可

値引数

指定不可

型引数

指定不可

備考

単純集計演算子の入出力

分類

名前

単位

型

備考

入力

in

グループ

任意

集計モデルの元になった型

出力

out

レコード

任意

集計結果、集計モデルの型

26

集計モデルについては DMDLユーザーガイド を参照してください。

27

com.asakusafw.vocabulary.operator.Summarize [https://docs.asakusafw.com/0.10.3/release/api/com/asakusafw/vocabulary/operator/Summarize.html]

NULL値に対する集約関数の動作

単純集計演算子を利用して集約するフィールドに null が含まれている場合、それぞれ以下のように動作します。

nullに対する集約関数の動作

集約関数

NULL値が含まれる場合の動作

any

NULL値も他の値と同様に取り扱う

sum

NullPointerException をスローする

max

NullPointerException をスローする

min

NullPointerException をスローする

count

NULL値も他の値と同様に取り扱う

単純集計演算子の実装

単純集計演算子の演算子メソッドには次のような情報を指定します。

単純集計演算子の実装

分類

対応

型

キー

備考

返戻

出力

モデル

不可

集計モデルのみ

引数1

入力

モデル

不可

集計モデルの元

この演算子は、単一の入力を特定の項目でグループ化し、グループ内で集計した結果を出力します。

このメソッドには本体を指定せず、抽象メソッドとして宣言します。

対象のメソッドは、集計対象のデータモデルオブジェクト型の引数を取ります。返戻型には集計結果を表す集計モデルの型を指定します。

この演算子のグループ化条件や集計方法は、集計モデル型の注釈 28 に全て埋め込まれているため、ここでは特に指定しません。

この演算子メソッドには型引数を定義できません。

単純集計演算子の演算子メソッドは、一般的な演算子メソッドの要件の他に、 下記の要件をすべて満たす必要があります。

返戻型に集計結果となる集計モデル型を指定する

以下の引数を宣言する

集計対象のデータモデルオブジェクト型の引数

以下の修飾子を付与する

abstract

以下の修飾子は付与しない

(特になし)

以下は実装例です。

/**
 * レコードHogeをHogeTotalに集計する。
 * @param hoge 集計対象
 * @return 集計結果
 */
@Summarize
public abstract HogeTotal summarize(Hoge hoge);

28

com.asakusafw.vocabulary.model.Summarized [https://docs.asakusafw.com/0.10.3/release/api/com/asakusafw/vocabulary/model/Summarized.html]

部分集約

単純集計演算子では、演算子注釈の partialAggregation を指定することで部分集約の設定を行えます。この要素には PartialAggregation 29 を指定でき、指定した値ごとに次のような動作をします。

部分集約の設定

指定する値

動作

TOTAL

部分集約を行わない

PARTIAL

常に部分集約を行う

DEFAULT

コンパイラオプションの設定に従う 30

部分集約を行う場合、この演算子はグループの計算が完了する前にグループごとに集計の計算を始め、データのコピーや転送を削減しようとします。単純集計演算子では部分集約可能な計算しか行いませんので、このオプションによって動作が変化することは基本的にありません。

Attention

基本的に、単純集計演算子では部分集約を行うべきです。初期値は PARTIAL になっています。

29

com.asakusafw.vocabulary.flow.processor.PartialAggregation [https://docs.asakusafw.com/0.10.3/release/api/com/asakusafw/vocabulary/flow/processor/PartialAggregation.html]

30

コンパイラオプションの設定については、以下の各コンパイラリファレンスを参照してください

Asakusa on Spark リファレンス - Asakusa DSL Compiler for Spark リファレンス

Asakusa on M3BPリファレンス - DSL Compiler for M3BPリファレンス

Asakusa on MapReduce リファレンス - Asakusa DSL Compiler for MapReduce リファレンス

畳み込み演算子

レコードをキーでグループ化し、グループ内のレコードを単一のレコードに畳み込む演算子です。畳み込みの前後でレコードの型は一致していなければならず、また畳み込みの順序は規定されません。

畳み込み演算子の概要

項目

説明

分類

ユーザー

導入

0.1

演算子注釈

Fold 31

本体の実装

必要

性能特性

Fold

入力数

1

出力数

1

ビュー引数

指定可能 32

値引数

指定可能

型引数

指定可能

備考

畳み込み演算子の入出力

分類

名前

単位

型

備考

入力

in

グループ

任意

グループ化を指定

出力

out

レコード

inと同様

畳みこみ結果

31

com.asakusafw.vocabulary.operator.Fold [https://docs.asakusafw.com/0.10.3/release/api/com/asakusafw/vocabulary/operator/Fold.html]

32

ただし、 部分集約 に PARTIAL を指定している場合はビュー引数を指定できません。

畳み込み演算子の実装

畳み込み演算子の演算子メソッドには次のような情報を指定します。

畳み込み演算子の実装

分類

対応

型

キー

備考

返戻

出力

void

不可

引数1

入出力

モデル

必須

畳み込み結果

引数2

入力

モデル

不可

引数1と同じ型を指定

ビュー引数

入力

ビュー

任意

部分集約 に PARTIAL を指定している場合は使用不可

値引数

なし

プリミティブ

不可

この演算子は、単一の入力を特定の項目でグループ化し、グループ内で畳みこんだ結果を出力します。

同じモデル型の二つの引数を取り、メソッドの本体で第一引数の内容を変更するプログラムを記述します。第一引数には Key 注釈を指定し、group でグループ化のためのプロパティ名を指定する必要があります。なお、整列のためのプロパティ名および整列方向は無視されます。

この演算子は次のように動作します。

引数1の Key 注釈に指定したグループ化条件で入力をグループ化

グループごとにそれぞれ以下の処理

グループ内の要素数が1になったら終了

そうでなければ、グループから要素を2つ取り除いて演算子メソッドを起動

演算子メソッドの引数1に指定したモデルをグループに書き戻す

グループ内の処理を繰り返す

グループ内の折りたたみは、引数2を元に引数1を破壊的に変更します。最後まで残った引数1の結果が、演算子の出力になります。

引数には同メソッドで宣言した型変数を利用できます。

畳み込み演算子の演算子メソッドは、一般的な演算子メソッドの要件の他に、 下記の要件をすべて満たす必要があります。

返戻型にvoidを指定する

以下の引数を宣言する

ここまでの畳み込みの結果を表すデータモデルオブジェクト型の引数、 さらに Key 注釈でグループ化のための情報を指定する

畳み込み対象のデータモデルオブジェクト型の引数

以下の修飾子を付与する

(特になし)

以下の修飾子は付与しない

abstract

以下は実装例です。

/**
 * レコードHogeを畳み込む。
 * @param left ここまでの畳み込みの結果
 * @param right 畳み込む対象
 */
@Fold
public void fold(@Key(group = "name") Hoge left, Hoge right) {
    // @Summarizeを手動で行うイメージで、leftに次々とrightを加える
    left.setValue(left.getValue() + right.getValue());
}

畳み込み演算子でも 部分集約 の指定が可能です。集約の指定方法は 単純集計演算子 と同様です。

Warning

畳み込み演算子で部分集約を利用する場合、演算子メソッドの本体でフレームワークAPIを利用できなくなります。これはAsakusa Frameworkの実装上の制約で、今後解消されるかもしれません。

グループ整列演算子

レコードをキーでグループ化し、さらにグループを特定の条件で整列させて操作する演算子です。この演算子は、 グループ結合演算子 を単一の入力に対して行うものです。

グループ整列演算子の概要

項目

説明

分類

ユーザー

導入

0.1

演算子注釈

GroupSort 33

本体の実装

必要

性能特性

CoGroup

入力数

1

出力数

任意

ビュー引数

指定可能

値引数

指定可能

型引数

指定可能

備考

グループ整列演算子の入出力

分類

名前

単位

型

備考

入力

in

グループ

任意

グループ化を指定

出力

(任意)

レコード

任意

任意個数を指定可

33

com.asakusafw.vocabulary.operator.GroupSort [https://docs.asakusafw.com/0.10.3/release/api/com/asakusafw/vocabulary/operator/GroupSort.html]

グループ整列演算子の実装

グループ整列演算子の演算子メソッドには次のような情報を指定します。

グループ整列演算子の実装

分類

対応

型

キー

備考

返戻

出力

void

不可

引数1

入力

リスト

必須

ビュー引数

入力

ビュー

任意

以降の引数

各出力

結果

不可

任意の個数

値引数

なし

プリミティブ

不可

この演算子は、単一の入力をグループ化し、グループ内で整列したリストとして処理した結果を出力します。

一つのデータモデルオブジェクトを要素に取るリスト型の引数と、複数の結果オブジェクト型の引数を取り、リストの任意の要素について加工を行った後に、結果オブジェクトに出力を行うプログラムを記述します。リスト型の引数には Key 注釈を指定し、グループ化のためのプロパティ名と整列のためのプロパティ名および整列方向を指定する必要があります。

引数には同メソッドで宣言した型変数を利用できますが、全ての結果オブジェクト型の出力に型変数を含める場合には、いずれかの入力に同様の型変数を指定してある必要があります。

グループ整列演算子の演算子メソッドは、一般的な演算子メソッドの要件の他に、 下記の要件をすべて満たす必要があります。

返戻型にvoidを指定する

以下の引数を宣言する

データモデルオブジェクトを要素に取るリスト型の引数、 さらに Key 注釈でグループ化と整列のための情報を指定する

一つ以上の結果型の引数

以下の修飾子を付与する

(特になし)

以下の修飾子は付与しない

abstract

グループ整列演算子は、入力の個数が1つに制限されているという点を除き、 グループ結合演算子 と同じ方法で記述できます。

以下は実装例です。

/**
 * レコードHogeを名前ごとに年齢の若い順に並べ、先頭と末尾だけをそれぞれ結果に流す。
 * @param hogeList グループごとのリスト
 * @param first グループごとの先頭要素
 * @param last グループごとの末尾要素
 */
@GroupSort
public void firstLast(
        @Key(group = "name", order = "+age") List<Hoge> hogeList,
        Result<Hoge> first,
        Result<Hoge> last) {
    first.add(hogeList.get(0));
    last.add(hogeList.get(hogeList.size() - 1));
}

Result インターフェースには複数件の結果を追加することもできます。

/**
 * レコードHogeを名前ごとに年齢の若い順に並べ、先頭の3件を結果に流す
 * @param hogeList グループごとのリスト
 * @param top3 グループごとの先頭3件の要素
 */
@GroupSort
public void topThree(
        @Key(group = "name", order = "+age") List<Hoge> hogeList,
        Result<Hoge> top3) {
    for (int i = 0; i < 3; i++) {
        top3.add(hogeList.get(i));
    }
}

なお、グループ整列演算子で巨大な入力グループを取り扱いたい場合、 グループ結合演算子 と同様に @Once や @Spill 注釈を指定します。詳しくは 巨大な入力グループへの対応 を参照してください。

特殊演算子

特殊系の演算子は、ここまでに紹介した分類に属さない特殊な演算子です。

フロー演算子

Flow DSLで定義したフロー部品を演算子として利用します。この演算子の入出力は、元となったフロー部品の入出力と一致します。

フロー演算子の概要

項目

説明

分類

特殊

導入

0.1

入力数

任意

出力数

任意

値引数

指定可

型引数

指定可

備考

フロー演算子の実装

フロー演算子はフロー部品を定義することで自動的に作成されます。フロー部品の定義方法は Asakusa DSLユーザーガイド を参照して下さい。

チェックポイント演算子

再試行がサポートされている実行エンジンで、再試行の開始ポイントのヒントを指定するための演算子です。

Attention

チェックポイント演算子は、ジョブフローのトランザクションとは無関係です。通常は明示的に指定する必要はありません。

チェックポイント演算子の概要

項目

説明

分類

コア

導入

0.1

メソッド

checkpoint

性能特性

Extract

入力数

1

出力数

1

チェックポイント演算子の入出力

分類

名前

単位

型

備考

入力

in

レコード

任意

出力

out

レコード

inと同様

チェックポイント演算子の実装

チェックポイント演算子はコア演算子に分類されるため、Operator DSLでの実装はありません。 Flow DSLからは次のように利用します。

In<Hoge> in;
Out<Hoge> out;

@Override
protected void describe() {
    CoreOperatorFactory core = new CoreOperatorFactory();
    Checkpoint<Hoge> op = core.checkpoint(in);
    out.add(op);
}

ロギング演算子

通過したデータごとにアプリケーションログを出力する演算子です。ログには以下のレベルがあります。

ログのレベル

レベル

概要

ERROR

重大な不具合

WARN

注意を要する不具合

INFO

分析のための情報

DEBUG

デバッグのための情報

このうち、 DEBUG はコンパイラの設定で有効または無効を切り替えられます。

ロギング演算子の概要

項目

説明

分類

ユーザー

導入

0.1

演算子注釈

Logging 34

本体の実装

必要

性能特性

Extract

入力数

1

出力数

1

ビュー引数

指定可能

値引数

指定可能

型引数

指定可能

備考

ロギング演算子の入出力

分類

名前

単位

型

備考

入力

in

レコード

任意

出力

out

レコード

inと同様

34

com.asakusafw.vocabulary.operator.Logging [https://docs.asakusafw.com/0.10.3/release/api/com/asakusafw/vocabulary/operator/Logging.html]

ロギング演算子の実装

ロギング演算子の演算子メソッドには次のような情報を指定します。

ロギング演算子の実装

分類

対応

型

キー

備考

返戻

なし

String

不可

引数1

入出力

モデル

不可

ビュー引数

入力

ビュー

任意

値引数

なし

プリミティブ

不可

この演算子は、入力されたデータをそのまま出力しますが、その際にロギングを行います。

メソッドの戻り値で返した文字列がログとして出力されます。また、ログはシステムに規定された方法で処理されます 35 。なお、引数のオブジェクトの内容を変更してはいけません。

ロギング演算子の演算子注釈は、 Logging.Level 36 を指定することでログのレベルを指定できます。この属性を指定しない場合は INFO レベルが使用されます。レベルについては ロギング演算子 を参照して下さい。

この演算子をフロー部品やジョブフローで使用する際に、出力 out は他の演算子等と結線されていなくてもエラーにならない、という特性を持ちます。

引数には同メソッドで宣言した型変数を利用できます。例えば上限境界の無い型引数を定義して、引数の型として利用すると、すべてのデータを受け取れるようなロギング演算子を定義することができます。

ロギング演算子の演算子メソッドは、一般的な演算子メソッドの要件の他に、 下記の要件をすべて満たす必要があります。

返戻型にStringを指定する

以下の引数を宣言する

データモデルオブジェクト型の引数

以下の修飾子を付与する

(特になし)

以下の修飾子は付与しない

abstract

以下は実装例です。

/**
 * エラーログを出力する。
 * @param hoge 更新するレコード
 */
@Logging(Logging.Level.ERROR)
public String error(Hoge hoge) {
    return MessageFormat.format("hoge = {0}", hoge.getValueOption());
}

35

ログの処理方法は、内部的には レポートAPI に処理を移譲しています。

36

com.asakusafw.vocabulary.operator.Logging.Level [https://docs.asakusafw.com/0.10.3/release/api/com/asakusafw/vocabulary/operator/Logging.Level.html]

空演算子

「データを流さない入力」を表す演算子です。フロー演算子 の利用しない入力に接続することを想定しています。

空演算子の概要

項目

説明

分類

コア

導入

0.1

メソッド

empty

性能特性

N/A

入力数

0

出力数

1

空演算子の入出力

分類

名前

単位

型

備考

出力

out

レコード

任意

空演算子の実装

空演算子はコア演算子に分類されるため、Operator DSLでの実装はありません。 Flow DSLからは次のように利用します。

@Override
protected void describe() {
    CoreOperatorFactory core = new CoreOperatorFactory();
    HogeOperatorFactory hoge = new HogeOperatorFactory();
    ...
    Empty<Hoge> op = core.empty(Hoge.class);
    Something something = hoge.something(op);
    ...
}

停止演算子

「データを流さない出力」を表す演算子です。各種演算子の利用しない出力に接続することを想定しています。

停止演算子の概要

項目

説明

分類

コア

導入

0.1

メソッド

stop

性能特性

N/A

入力数

1

出力数

0

停止演算子の入出力

分類

名前

単位

型

備考

入力

in

レコード

任意

Note

Flow DSLではすべての演算子の出力が何らかに接続されていなければなりません。これは接続漏れなどによる実装バグなどを検出するための措置です。

停止演算子の実装

停止演算子はコア演算子に分類されるため、Operator DSLでの実装はありません。 Flow DSLからは次のように利用します。

In<Hoge> in;

@Override
protected void describe() {
    CoreOperatorFactory core = new CoreOperatorFactory();
    HogeOperatorFactory hoge = new HogeOperatorFactory();
    Something something = hoge.something(in);
    core.stop(something.unnecessary);
}

補助演算子

補助演算子は単体で演算子としては機能せず、他の演算子と組み合わせて利用する注釈です。

マスタ選択

マスタ選択は、以下の演算子において非等価結合を実現するための補助演算子です。

マスタ確認演算子

マスタ結合演算子

マスタ分岐演算子

マスタつき更新演算子

それぞれの演算子注釈には共通して selection という注釈要素を指定可能です。この要素にメソッド名を指定し、同じ演算子クラス内に指定したメソッド名で、注釈 MasterSelection 37 を付与したパブリックメソッドを宣言します。

このメソッドは次のように宣言します。

マスタ選択の実装

分類

対応

型

キー

備考

返戻

入力

モデル

不可

選択結果のマスタデータ

引数1

入力

リスト

不可

選択対象のマスタ一覧

引数2

入力

モデル

不可

ビュー引数

入力

ビュー

不可

値引数

なし

プリミティブ

不可

この演算子は、トランザクションデータに対応する複数のマスタデータを引き当てたのち、実際に利用するマスタデータを選択します。つまり、等価結合のみしか行えない環境において、重複するマスタデータから複雑な条件でマスタデータを選択するために利用することができます。

対象のメソッドは、マスタデータを表すデータモデルオブジェクトを要素に取るリスト型の引数と、トランザクションデータを表すデータモデルオブジェクト型の引数を順に取ります。いずれも Key 注釈は不要です。

メソッドの本体ではマスタデータを選択し、一つだけ選んで戻り値として返します。戻り値に null を返した場合にはマスタの引当に失敗した扱いになります。なお、各引数の内容を変更した際の動作は規定されません。

返戻値の型と、引数1の要素型はマスタ選択演算子を利用する演算子の引数1と同じ型である必要があります。また、引数2以降はそれぞれマスタ選択演算子を利用する演算子メソッドの引数と同じ型である必要があります。なお、引数2以降は省略可能です。

マスタ選択演算子を指定した演算子メソッドが実行されると、その演算子の処理が実行される前に、マスタ選択演算子のメソッドが起動されます。その際、マスタデータが指定したグループ化条件に従ってリストに詰められて、マスタ選択演算子メソッドの引数として与えられます。そして、マスタ選択演算子メソッドの戻り値を引数として、元の演算子メソッドが実行されます。

この注釈を付与するメソッドは、下記の要件を満たす必要があります。

返戻型に結合対象のデータモデルオブジェクト型(マスタデータ)を指定する

以下の引数を宣言する

結合対象のデータモデルオブジェクト型の引数 (マスタデータ)

結合対象のデータモデルオブジェクト型の引数

以下の修飾子を付与する

(特になし)

以下の修飾子は付与しない

abstract

以下は実装例です。

/**
 * 有効なマスタを選択する。
 * @param masters 選択対象のマスタデータ一覧
 * @param tx トランザクションデータ
 * @return 実際に利用するマスタデータ、利用可能なものがない場合はnull
 */
@MasterSelection
public ItemMst selectItemMst(List<ItemMst> masters, HogeTrn tx) {
    for (ItemMst mst : masters) {
        if (mst.getStart() <= tx.getDate() &&
                tx.getDate() <= mst.getEnd()) {
            return mst;
        }
    }
    return null;
}

マスタ選択演算子を利用する演算子は、かならず同じクラス内に宣言する必要があります。また、その演算子は同一種類のマスタおよびトランザクションデータを取り扱う必要があります。

以下は、マスタ選択演算子を使用する演算子メソッドの実装例です。

/**
 * マスタの価格をトランザクションデータに設定する。
 * @param master マスタデータ
 * @param tx 変更するトランザクションデータ
 */
@MasterJoinUpdate(selection = "selectItemMst")
public void updateWithMaster(
        @Key(group = "id") ItemMst master,
        @Key(group = "itemId") HogeTrn tx) {
    tx.setPrice(master.getPrice());
}

37

com.asakusafw.vocabulary.operator.MasterSelection [https://docs.asakusafw.com/0.10.3/release/api/com/asakusafw/vocabulary/operator/MasterSelection.html]

多重化抑制

多重化抑制は演算子メソッドに追加で指定する注釈で、コンパイラの多重化に関する最適化を抑止します。コンパイラは最適化の過程で、単一の演算子を複数個に分解して並列性を確保します。このため、同じデータに対して処理が複数回実行される場合があり、毎回異なる結果を出力するような演算子では期待した結果が得られない場合があります。

多重化を抑制する場合には、次のように注釈 Volatile 38 を演算子メソッドに指定します。

/**
 * ランダムに分岐する。
 * @param hoge 対象のレコード
 * @return 分岐先を表すオブジェクト
 */
@Volatile
@Branch
public Status select(Hoge hoge) {
    if (Math.random() < 0.5) {
        return Status.SMALL;
    } else {
        return Status.BIG;
    }
}

上記の場合、レコードはそれぞれ SMALL か BIG のいずれかのみに出力されるのが通常です。しかし、多重化抑制の指定がない場合には、この演算子はレコードを両方に出力する場合や、いずれにも出力しない場合など予期せぬ動作をする場合があります。

その他、以下のケースなどでは多重化抑止が有効です。

ユニークな値を採番する

実行時の時刻などを利用する

入力の個数を計測する

38

com.asakusafw.vocabulary.operator.Volatile [https://docs.asakusafw.com/0.10.3/release/api/com/asakusafw/vocabulary/operator/Volatile.html]

除去抑制

除去抑制は演算子メソッドに追加で指定する注釈で、コンパイラの除去に関する最適化を抑止します。コンパイラは最適化の過程で、最終的なジョブフローの出力に到達しない演算子の処理をすべて除去します。このため、副作用のみを期待するような演算子を配置しても、期待した動作を行いません。

除去を抑制する場合には、次のように注釈 Sticky 39 を演算子メソッドに指定します。

/**
 * 例外をスローする。
 * @param hoge 対象のレコード
 */
@Sticky
@Update
public void raise(Hoge hoge) {
    throw new IllegalStateException();
}

上記の更新演算子は直後に 停止演算子 によって出力を抑制され、ジョブフローの出力に接続されていないものとします。除去抑制の指定がない場合、この演算子はコンパイラによって「不要な演算子」と判断され、例外がスローされることはありません。

上記のように除去抑制が指定されている場合にはこの演算子は消去されず、この演算子の入力にデータが流れた瞬間に例外がスローされます。

39

com.asakusafw.vocabulary.operator.Sticky [https://docs.asakusafw.com/0.10.3/release/api/com/asakusafw/vocabulary/operator/Sticky.html]

多相データフロー

概要

多相データフローはAsakusa DSLの拡張機能です。多相データフローにより、複数のデータモデルに対する共通の処理をまとめて定義できるようになります。

複数のデータモデルに対して共通の処理を実装するような場合、データモデルの種類ごとに個別のデータフローや演算子を定義するかわりに多相データフローを利用することで効率的に実装を行うことが出来ます。

射影モデル

多相データフローでは具体的なデータモデルを取り扱うのではなく、「射影モデル」というデータモデルの一部を投影した汎用的なデータ構造を取り扱います。

射影モデルは各データモデルが共通して持つプロパティの一覧を抽出した部分的なデータ構造を表し、次のような特徴を持っています。

射影モデルのプロパティは、抽出元の同じプロパティと常に同じ値を持つ

射影モデルのプロパティを変更すると、抽出元の同じプロパティも同様に変更される

このような射影モデルに対するデータフローや演算子を定義することで、同じ射影モデルを抽出できる複数のデータモデルに対して汎用的な処理を記述できます。

この文書では以後、通常のデータモデルを単に「データモデル」とよび、データモデルの射影を表すモデルを「射影モデル」と呼ぶことにします。また、データモデルの一部を射影モデルとして取り出すことを、データモデルを射影モデルに「投影する」と呼ぶことにします。

Asakusa DSLでの射影モデル

Asakusa DSLでは、データモデルをJavaのクラスで表し、射影モデルをJavaのインターフェースで表します。また、それぞれのデータモデルの実体(instance)は、データモデルに対応するJavaのクラスをインスタンス化したオブジェクトとして表します。

データモデルと射影モデルの関係は、Javaの継承関係で表します。つまり、データモデルをある射影モデルに投影できる場合、データモデルに対応するクラスは、その射影モデルに対応するインターフェースを実装(implements)することになります。

あるデータモデルの実体を射影モデルの実体に投影する操作は、対応するオブジェクトの型を、データモデルの型から射影モデルの型に拡大変換することで表します。つまり、Asakusa DSLにおいて、射影モデルの実体は投影元のデータモデルの実体と一致します。

射影モデルを定義する方法は、 DMDLユーザーガイド を参照して下さい。

Attention

このような実装のため、Asakusa DSLでデータモデルを射影モデルに投影するには、あらかじめデータモデルが対象の射影モデルを実装している必要があります。継承関係にないデータモデルと射影モデルは、たとえ両者のプロパティの構造が同じであっても投影できません。

Operator DSLの多相化

多相データフローの導入により、Operator DSLで定義する演算子が射影モデルを取り扱えるようになります。

射影モデルを取り扱う演算子を、以後「多相演算子」と呼びます。

多相演算子

多相演算子は、従来の演算子メソッドの宣言をJavaの総称メソッドとして宣言します。

総称メソッドの型引数には、射影モデルを表す型を上限境界に指定して、その型引数を演算子メソッドの引数に利用します。

@Update
public <T extends PModel>
void example(T model) {
     model.setValue(100);
}

型引数をとる演算子メソッドは、Operator DSLコンパイラによって多相演算子として取り扱われます。

上記の演算子は、 PModel という射影モデルのインターフェースを実装したすべてのデータモデルに対して利用できます。

多相演算子の制限

多相演算子には次のような制限があります。

入出力の引数型に射影モデルを直接指定できない。必ず型変数の上限境界に指定する必要がある

出力に型変数を利用する場合、入力の型から一意に推論できるデータモデル型である必要がある

上記の制約により、入力と出力の型に直接の関係が無いような演算子については、出力に射影モデルを指定できません。これは、以下のような演算子が該当します。

変換演算子

マスタ結合演算子

単純集計演算子

合成射影

データモデルを複数の種類の射影モデルに投影することもできます。

これら複数の射影モデルを合成した射影を利用する場合、型引数の上限境界に複数の射影モデルを同時に指定します。

@Update
public <T extends A & B>
void example(T model) {
     model.setA(100);
     model.setB(200);
}

このとき、型変数 T は「 A と B のプロパティをすべて利用できる型」として合成した射影モデルのように取り扱えます。また、この演算子に利用できるデータモデルは、 A と B のどちらにも投影可能でなければなりません。

キー項目の指定

型変数を利用した射影モデルの引数に、キー項目の情報を表す @Key 注釈を指定する場合、そこに指定できるプロパティは必ず射影に含まれていなければなりません。

以下は、 @Key 注釈を指定する例です。プロパティ key が PKey または PValue のいずれかに宣言されている必要があります。

@MasterJoinUpdate
public <P extends PKey & PValue>
void branchProjection(
          @Key(group = "key") P mst,
          @Key(group = "key") TxData tx) {
     tx.setValue(mst.getValue());
}

上記のマスタつき更新演算子は、マスタの入力に PKey と PValue をどちらも実装したデータモデルを指定できます。

Flow DSLの多相化

多相データフローの導入により、Flow DSLでは多相演算子を利用できるようになります。さらに、フロー部品そのものを多相演算子として利用できるようにもなります。

演算子オブジェクトのパラメータ化

Operator DSLで多相演算子を作成した場合、Flow DSLでもその演算子オブジェクトに型引数を指定します。この型引数には、それぞれ射影モデルが上限境界として設定されていて、実際のデータモデルの型を型引数に指定することで、「そのデータモデルに対する演算子」として利用できるようになります。

例として、データモデルの型 DModel と、そこから投影できる射影モデル PModel について考えます。

次のような PModel に対する更新演算子をOperator DSLで定義したとします。

@Update
public <P extends PModel>
void updateProjection(P model) {
     model.setProjectiveMember(100);
}

Flow DSLでは、上記の演算子に対して DModel 型の入力を利用できます。

In<DModel> in;
Out<DModel> out;
...
UpdateProjection<DModel> op = factory.updateProjection(in);
out.add(op.out);

なお、更新演算子は入力と出力に同じ型をとるような演算子です。このため、 DModel を入力にとる更新演算子の出力は、同じように DModel となります。

Note

入力のみを多相化する演算子では、型変数の定義は本来不要です。これは、型変数が出力の型文脈を表現するためにのみ利用されるため、出力が多相化されていない限り、演算子オブジェクトが型引数を伴う必要は本来ありません。

今回は規則の簡単化のため、そのような場合においても演算子オブジェクトは演算子メソッドで宣言された全ての型引数を引き継ぐものとします。

フロー部品の多相化

Flow DSLで定義されたフロー部品は、他のフローから演算子として利用できます。フロー部品そのものを多相化する場合には、多相演算子とほとんど同様の方法でフロー部品クラスを総称化します。

多相化したフロー部品は、コンストラクタの引数に型引数を利用できます。これにより、データフローの一部を操作対象の射影モデルに対して定義できるようになります。なお、このように多相化されたフロー部品を「多相フロー部品」とよびます。

例として、これまでと同様にデータモデルの型 DModel と、そこから投影できる射影モデル PModel について考えます。多相フロー部品を定義するには、フロー部品クラスそのものを総称クラスとして宣言し、型引数の上限境界に射影モデルを指定します。

@FlowPart
public class FlowProjection<P extends PModel> extends FlowDescription {
     In<P> in;
     Out<P> out;
     public FlowProjection(In<P> in, Out<P> out) {
          ...
     }
     ...
}

上記のフロー部品の内部では、型変数 P を利用してデータフローを記述できます。これはつまり、 PModel を利用する多相演算子をこのデータフローから利用できます。

たとえば、以下のような多相化された更新演算子があるとします。

@Update
public <P extends PModel>
void updateProjection(P model) {
     model.setProjectiveMember(100);
}

フロー部品の describe メソッドでは、上記の多相演算子を次のように利用できます。

In<P> in;
Out<P> out;
...
@Override protected void describe() {
     UpdateProjection<P> op = factory.updateProjection(in);
     out.add(op.out); // UpdateProjection<T>.out : Source<T>
}

なお、多相フロー部品は他のデータフローから多相演算子として利用できます。

In<DModel> in;
Out<DModel> out;
...
FlowProjection<DModel> op = factory.create(in);
out.add(op.out); // FlowProjection<T>.out : Source<T>

多相フロー部品の出力型

フロー部品では、入力または java.lang.Class 型の引数のいずれかで指定した型変数を出力でも利用できます 1 。

たとえば、次のようなフロー部品を記述できます。

@FlowPart
public class GenericWithClass<
        A extends Hoge,
        B extends Foo> extends FlowDescription {

    private In<A> in;
    private Out<B> out;
    private Class<B> type;

    public GenericWithClass(In<A> in, Out<B> out, Class<B> type) {
        this.in = in;
        this.out = out;
        this.type = type;
    }

    @Override
    protected void describe() {
        CoreOperatorFactory c = new CoreOperatorFactory();
        out.add(c.project(in, type));
    }
}

上記の出力 out は型変数 B を利用しています。通常の多相演算子ではこの型変数 B は入力にも利用されていなければなりませんが、多相フロー部品の場合には代わりに Class<B> type で利用しているためエラーとなりません。

Note

java.lang.Class を利用した多相フロー部品は、拡張演算子や射影演算子との連携を考えて設計されています。これらの演算子については 演算子リファレンス を参照してください。

1

通常の多相演算子での制約については、 多相演算子の制限 を参照してください。

ビューAPI

ビューAPIはAsakusa DSLの拡張機能で、データフロー上の任意の中間出力を、演算子から柔軟に参照するためのインターフェースを提供します。ビューは主にバッチ全体の定数表を効率よく扱うためのしくみで、以下のような定数データを外部データソースから取り込んで演算子メソッドから利用できます。

以下は「消費税率」などの税率テーブルをデータベースなどに保持し、演算子内から参照するサンプルコード片です。

private static final StringOption KEY_CTAX = new StringOption("消費税");

/**
 * 消費税を計算する。
 * @param detail 販売明細
 * @param taxTable 税率テーブル
 */
@Update
public void updateTax(
        SalesDetail detail,
        @Key(group = "name") GroupView<TaxEntry> taxTable) {

    // 税率テーブルから「消費税」に関する情報を取得する
    TaxEntry tax = taxTable.find(KEY_CTAX).get(0);

    // 総額から本体価格を算出する
    BigDecimal totalPrice = BigDecimal.valueOf(detail.getSellingPrice());
    BigDecimal priceWithoutTax = totalPrice.divide(BigDecimal.ONE.add(tax.getRate()));

    // ...
}

また、バッチ内で作成した中間データ（集計結果など）を上記と同様に定数表として参照したり、柔軟なテーブル化の機能を利用して複雑な条件を伴う結合処理（例えばデータ範囲を条件とする結合）などを、効率よく実現したりすることが可能です。

Attention

Asakusa on MapReduceではビューAPIを利用できません。

概要

ビューAPIを利用することで、Asakusa DSLで以下のようなデータアクセスが可能になります。

Direct I/OやWindGateなどの外部入力データに、任意の演算子から読み取り専用でアクセスする。

任意の演算子の途中結果に、任意の演算子から読み取り専用でアクセスする。

結合演算子を利用した結合系処理とは異なり、付き合わせを行うことなく指定したデータの全体に参照する。

ビューAPIを使用するには、ビューAPIが提供するインターフェースを演算子メソッドの引数（ビュー引数）として指定します。ビュー引数を経由して、ビューに指定した入力に対するすべてのレコードにアクセスすることができます。

ビューAPIには、参照するデータ全体を順次参照するための View 1 インターフェースと、特定のキーを持つグループを選択して参照するための GroupView 2 インターフェースがあります。

GroupView インターフェースは、View インターフェースの機能に加えて、以下の機能を提供します。

パーティショニング用のキーを指定し、キーに対するグループ単位でレコードにアクセスする。

グループ化するデータセットに対して任意の整列順序を指定する。

グループ化や整列が処理効率に影響するような処理を記述する場合は、GroupView インターフェースの利用を推奨します。

1

com.asakusafw.runtime.core.View [https://docs.asakusafw.com/0.10.3/release/api/com/asakusafw/runtime/core/View.html]

2

com.asakusafw.runtime.core.GroupView [https://docs.asakusafw.com/0.10.3/release/api/com/asakusafw/runtime/core/GroupView.html]

ビューAPIの利用方法

ビューAPIを利用したバッチアプリケーションを作成するには、まずOprator DSL上でビューAPIインターフェースを利用した演算子メソッドを作成します。Flow DSL上ではその演算子に対して、従来と同様の方法でデータフローの入力を指定します。

演算子メソッドの定義

ビューAPIを利用する演算子メソッドを作成するには、メソッドの引数を定義する際に 入力データを受け取る引数の直後 に View<T> 、または GroupView<T> の引数を指定します。型変数 T にはこのAPIを通してアクセスするデータモデルクラスの型を指定します。

以下は、更新演算子で View を利用する演算子メソッドの定義例です。

@Update
public void updateWithView(
        SalesDetail sales,
        View<Foo> view) {
    ...
}

GroupView を利用する場合には以下の例のように GroupView<T> の直前に @Key 注釈 ( キー注釈 )を指定して、グループ化キー ( group )を指定する必要があります。また、 order を指定することで、グループ内の要素の順序を指定できます。

以下は、抽出演算子で GroupView を利用する演算子メソッドの定義例です。 GroupView を定義する引数の位置に注目してください。

@Extract
public void extractWithGroupView(
        SalesDetail sales,
        @Key(group = "store_code", order = "id") GroupView<Foo> view,
        Result<SalesDetail> result,
        Result<ErrorRecord> error) {
    ...
}

演算子メソッドの実装

View<T> は Iterable<T> インターフェースを継承しています。そのため、View<T> からレコードにアクセスするには拡張for文(for-each文)などを利用することができます。この方法でレコードにアクセスする場合、取り出されるレコードの整列順序は不定です。

@Update
public void updateWithView(
        SalesDetail sales,
        View<Foo> view) {

    for (Foo foo : view) {
        ...
    }
}

GroupView<T> では find メソッドを使用して、キー注釈で指定したグループに対応するレコードを List<T> として取得できます。このリストに含まれるレコードはキー注釈で指定した整列順序で整列されています。

@Extract
public void extractWithGroupView(
        SalesDetail sales,
        @Key(group = "store_code", order = "id") GroupView<Foo> view,
        Result<SalesDetail> result,
        Result<ErrorRecord> error) {

    List<Foo> fooList = view.find(sales.getStoreCodeOption());
    ...
}

Attention

GroupView<T> は View<T> のサブインターフェースであるため、 View<T> と同様の方法でもレコードにアクセスすることもできます。ただしこの方法ではキー注釈で指定した整列順序は不定です。

find メソッドに指定する引数には、キー注釈で指定したグループに対応したデータ項目を入力のデータモデルクラスから指定します。このとき、引数に指定する値はデータモデルクラスの getXXXOption で取得できる ValueOption のサブクラスを指定する必要があります。

上記の例では、 GroupView<Foo> view にはキー注釈でDMDLのTEXT型として定義した store_code をグループとして指定しているので、 このビューの find メソッドに指定可能な引数は1つで、その型は StringOption になります。

Attention

上記の例では find メソッドに sales.getStoreCodeOption() で返される StringOption 型を指定することができますが、 sales.getStoreCode() で返される Text 型や sales.getStoreCodeAsString() で返される String 型を指定することはできません。

Attention

find メソッドに指定する引数の数は、必ずキー注釈で指定したグループの個数と同じ数を指定してください。引数の数が一致しない場合でもコンパイルエラーにはなりませんが、実行時には正しく動作しません。

演算子メソッド実装の制約

ビューAPIで取得するすべてのオブジェクトはメモリ上に保持されます。ビューAPIで取得するレコード数が膨大となる場合、メモリ不足で実行に失敗する可能性があります。

ビューAPI経由で取得したデータモデルオブジェクトの内容は変更できません。変更した場合の実行結果は不定です。

ビューAPI経由で取得したデータモデルオブジェクトの値を演算子の出力に指定することはできません。ただしデータモデルオブジェクトの値をコピーして、その値を出力に指定することは可能です。

メソッド本体の実装が不要なユーザー演算子に対して、ビューAPIを使用することはできません。ただし例外として、マスタ選択( @MasterSelection )補助演算子を伴う演算子については、実装が不要な演算子に対してビューAPIを使用することができます。

畳み込み演算子( @Fold )では部分集約を有効にしている場合、ビュー引数を指定することはできません。

See also

各演算子の詳細については、 演算子リファレンス を参照してください。

演算子メソッドの例

複数のビュー

演算子では任意の個数のビューを利用することができます。

@MasterJoinUpdate
public void masterJoinWithGroupView(
        @Key(group = "store_code") StoreInfo store,
        @Key(group = "store_code") SalesDetail sales,
        @Key(group = "store_code") GroupView<StoreInfo> viewStoreA,
        @Key(group = "store_code") GroupView<StoreInfo> viewStoreB,
        @Key(group = "store_code") GroupView<StoreInfo> viewStoreC
        ) {
    ...
}

値引数を含む演算子

値引数を利用する演算子メソッドでビューを利用する場合、引数の順序は以下のようになります

入力データを受け取る引数

ビュー引数

出力データを格納する引数

値引数

@GroupSort
public void groupSortWithView(
        @Key(group = "store_code", order = "amount DESC") List<SalesDetail> sales,
        View<ItemInfo> viewItem,
        Result<SalesDetail> result,
        int numberOfRank) {
    ...
}

マスタ選択演算子の利用

マスタ選択演算子でビューを利用するには、対応する演算子側にもビュー引数を定義する必要があります。

@MasterCheck(selection = "selectAvailableItem")
public abstract boolean masterSelectionWithGroupView(
        @Key(group = "item_code") ItemInfo info,
        @Key(group = "item_code") SalesDetail sales,
        @Key(group = "item_code") GroupView<ItemInfo> viewItem);

@MasterSelection
public ItemInfo selectAvailableItem(
        List<ItemInfo> candidates,
        SalesDetail sales,
        GroupView<ItemInfo> viewItem) {
    ...
}

GroupView を利用する場合、グループ化の定義は対応する演算子側のキー注釈の定義が利用されます。マスタ選択演算子側にキー注釈を指定しても、その内容は無視されます。

グループ化キーの定義

GroupView で指定するグループ化キーは、結合のためのキーとは別の項目を指定することができます。

@CoGroup
public void cogroupViewGroupView(
        @Key(group = "store_code") List<SalesDetail> salesA,
        @Key(group = "store_code") List<SalesDetail> salesB,
        @Key(group = "item_code") GroupView<ItemInfo> viewItem,
        Result<Foo> result) {
    ...
}

フロー記述メソッドの実装

Flow DSLでビューAPIを使用した演算子を利用するデータフローを記述するには、通常の演算子の入力を指定する方法と同じように、演算子に定義した入力に対してデータフローの接続を指定します。

@FlowPart
public class WithViewFlowPart extends FlowDescription {

    final In<SalesDetail> salesDetail;
    final In<Foo> fooView;
    ...

    @Override
    protected void describe() {
        WithViewOperatorFactory operators = new WithViewOperatorFactory();
        UpdateWithView updateWithView = operators.updateWithView(salesDetail, fooView);
        ...
    }

}

この例では updateWithView 演算子に2つの入力を渡しています。第1引数は通常の入力、第2引数はビューAPIを使用して定義した入力ですが、Flow DSLでは両者の入力は同じように取り扱うことができます。

テスト方法

演算子メソッドのテスト

演算子のテストでは、DataLoader を利用して View<T> や GroupView<T> に対応するデータモデルオブジェクトを生成することができます。

詳しくは、テストドライバーユーザーガイド - 演算子のテスト - ビューAPIを使った演算子のテスト を参照してください。

データフローのテスト

ビューAPIを使用する演算子を含むデータフローは、通常のデータフローと同様の方法でテストを記述することができます。

詳しくは テストドライバーユーザーガイド - データフローのテスト などを参照してください。

Asakusa DSL開発者ガイド

この文書では、Asakusa DSLおよびAsakusa DSLコンパイラの拡張方法について紹介します。

Todo

Asakusa DSL > Developer Guide

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

Asakusa Frameworkでは、 アプリケーションの実装 - Asakusa DSL で記述したバッチアプリケーションの自動テストを作成する多くのテスト機能を提供しています。

関連するドキュメント

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

テストドライバーユーザーガイド

Excelによるテストデータ定義

JSONによるテストデータ定義

テストドライバー開発者ガイド

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

この文書では、Asakusa Frameworkを使った作成したバッチアプリケーションをテストする方法について簡単に紹介します。

See also

テストのより詳しい情報は テストドライバーユーザーガイド を参照して下さい。

演算子のテスト

Operator DSLを使って記述した演算子に対するテストの方法は、以下の2種類の方法が提供されています。

演算子クラスに対するテスト

一時的なフロー記述に対するテスト

演算子クラスに対するテスト

この方法は、演算子のテストを一般的なクラスに対する単体テストと同様の方法で作成します。

このテストでは、演算子クラスに記述した演算子メソッドにテストデータとして用意したデータモデルオブジェクトを渡して実行し、変更されたデータモデルオブジェクトの内容やメソッドの戻り値をJUnitのAPIなどを使って検証します。

演算子クラスは抽象クラスとして宣言しているため、テストメソッド内では演算子実装クラス（演算子クラス名の末尾に Impl を付与したクラスで、Operator DSLコンパイラが自動的に生成する）のインスタンスから演算子メソッドを呼び出します。

詳しくは、以下を参照してください。

テストドライバーユーザーガイド - 演算子クラスに対するテスト

一時的なフロー記述に対するテスト

この方法は、演算子のテストを データフローのテスト と同様の方法で作成します。

このテストでは、テストドライバーを使って「一時的なフロー記述」（テスト専用のデータフロー）を作成し、そのデータフローにテスト対象の演算子を含めて実行するテストケースを記述します。テストデータのセットアップや実行結果の検証はテストドライバーの機能を利用します。

この方法は 演算子クラスに対するテスト と比べ、以下のようなメリットがあります。

複数の演算子を組み合わせたテストケースの作成が可能

複雑なテストデータ（入力データ、期待データ、テスト条件）を定義する様々な機能を利用可能

演算子とデータフローのテストを統一的な方法で記述することが可能

詳しくは、以下を参照してください。

テストドライバーユーザーガイド - 一時的なフロー記述に対するテスト

データフローのテスト

Flow DSLを使って記述したデータフロー、およびBatch DSLを使って記述したバッチに対するテストでは、DSLのコンパイラや実行環境と連携してテストを実行します。

テストドライバー

Asakusa Frameworkにはテストドライバーというテスト開発用のJavaライブラリが含まれています。これには次のような特徴があります。

テスト用の実行エンジンや外部システム連携モジュールと自動的に連携したテストが可能

様々な形式でテストデータ（入力データ、期待データ、検証ルール）を作成する機能を提供

JUnitなどの様々なテストハーネスから利用可能

また、 アプリケーションの実装 - Asakusa Data Model の機能と連携してテストケースの入出力データや検査ルールのテンプレートを生成するツールも提供しています。

テストドライバーはテスト対象の要素に対して、次の一連の処理を行います。

入力データを初期化する

入力データを流し込む

対象のプログラムをテスト用の実行エンジン向けにDSLコンパイルする

対象のプログラムを実行する

出力結果を取り込む

出力結果と期待データを検証する

詳しくは、以下を参照してください。

テストドライバーユーザーガイド - データフローのテスト

テストデータの作成

テストドライバーでのテストを行うには、次の3種類の情報を用意します。これらをまとめて「テストデータ」と呼ぶことにします。

入力データ

それぞれのデータフローの入力に指定するデータセット。データモデルオブジェクトのリストと同じ構造。

期待データ

それぞれのデータフローからの出力に期待するデータセット。入力データと同じ構造。

テスト条件

それぞれの出力と期待データを比較して間違いを見つける方法。

テストドライバーはテストデータをさまざまな形式で記述できます。テストドライバーがサポートしているテストデータの形式には以下のようなものがあります。

Excelファイル形式

JSONファイル形式

Direct I/Oファイル形式 ( CSV, TSVファイルなど )

Javaクラス(オブジェクト)

詳しくは、以下を参照してください。

テストドライバーユーザーガイド - テストデータの作成

テストのデバッグと実行結果の分析

テストドライバーではテストのデバッグや実行結果の分析を支援する、以下のような機能を提供しています。

データフローの出力結果を保存する

テスト実行の比較結果を保存する

演算子のトレースログを出力する

また、テストクラス自体はJUnitをはじめとした任意のテストハーネスを利用できるため、Javaの既存プロダクトと連携した継続的インテグレーション(Continuous Integration)環境を構築し、これらのレポート機能と連携することなども可能です。

詳しくは、以下を参照してください。

テストドライバーユーザーガイド - その他のオプション

テストドライバーユーザーガイド

この文書では、Asakusa Frameworkを使ったバッチアプリケーションをテストする方法について紹介します。

本書ではテストケースの実装に JUnit [http://www.junit.org/] を利用します。

演算子のテスト

Operator DSL 1 を使って記述した演算子に対するテストの方法は、以下の2種類の方法が提供されています。

演算子クラスに対するテスト

一時的なフロー記述に対するテスト

1

Operator DSLについて詳しくは Asakusa DSLユーザーガイド - Operator DSL などを参照してください。

演算子クラスに対するテスト

この方法は、演算子のテストを一般的なクラスに対する単体テストと同様の方法で作成します。

このテストでは、演算子クラスに記述した演算子メソッドにテストデータとして用意したデータモデルオブジェクトを渡して実行し、変更されたデータモデルオブジェクトの内容やメソッドの戻り値をJUnitのAPIなどを使って検証します。

演算子クラスは抽象クラスとして宣言しているため、テストメソッド内では演算子実装クラス（演算子クラス名の末尾に Impl を付与したクラスで、Operator DSLコンパイラが自動的に生成する）のインスタンスから演算子メソッドを呼び出します。

@Test
public void testCheckShipment_shipped() {
    StockOp operator = new StockOpImpl();
    Shipment shipment = new Shipment();
    shipment.setShippedDate(new DateTime());
    shipment.setCost(100);

    ShipmentStatus actual = operator.checkShipment(shipment);

    assertThat("COSTが指定されていたらCOMPLETED",
            actual, is(ShipmentStatus.COMPLETED));
}

以降では、演算子のテストを記述を補助するテストAPIについて説明します。

OperatorTestEnvironment

いくつかの演算子のテストには、 OperatorTestEnvironment 2 クラスを利用します。このクラスはAsakusaのフレームワークAPIをテスト時にエミュレーションするためのもので、フレームワークAPIを利用する演算子をテストする場合には必須です。その他、 OperatorTestEnvironment は演算子のテスト実装に便利なユーティリティメソッドを提供します。

OperatorTestEnvironment クラスは、テストクラスの public フィールドに @Rule 3 という注釈を付けてインスタンス化します。

// 必ずpublicで宣言し、インスタンスを代入する
@Rule
public OperatorTestEnvironment env = new OperatorTestEnvironment();

OperatorTestEnvironment 利用の一例として、演算子クラスのインスタンスを生成する newInstance の使用例を示します。 newInstance は指定した演算子クラスに対する実装クラスを返します。

例えば先述のテストメソッド例に対しては、演算子クラスのインスタンス生成部分を以下のように書き換えることができます。

@Test
public void testCheckShipment_shipped() {
    StockOp operator = env.newInstance(StockOp.class);
    ...

2

com.asakusafw.testdriver.OperatorTestEnvironment [https://docs.asakusafw.com/0.10.3/release/api/com/asakusafw/testdriver/OperatorTestEnvironment.html]

3

org.junit.Rule

結果型を利用する演算子のテスト

いくつかの演算子メソッドでは、出力を表す Result 4 型のオブジェクトを引数に取ります。これを利用するメソッドのテストには、モック実装の MockResult 5 が便利です。

@Rule
public OperatorTestEnvironment env = new OperatorTestEnvironment();

@Test
public void testCutoff_shortage() {
    StockOp operator = env.newInstance(StockOp.class);

    List<Stock> stocks = Arrays.asList(StockFactory.create(new DateTime(), 0, 100, 10));
    List<Shipment> shipments = Arrays.asList();
    MockResult<Stock> newStocks = env.newResult(Stock.class);
    MockResult<Shipment> newShipments = env.newResult(Shipment.class);

    operator.cutoff(stocks, shipments, newStocks, newShipments);

    assertThat(newStocks.getResults().size(), is(1));
    assertThat(newShipments.getResults().size(), is(0));
}

Note

バージョン 0.9.1 以降では、 MockResult インスタンスを生成するファクトリメソッド OperatorTestEnvironment#newResult が利用できます。通常はこのメソッドを使って MockResult を生成することを推奨します。

なお、結果型を引数に指定する演算子については 演算子リファレンス を参照してください。

4

com.asakusafw.runtime.core.Result [https://docs.asakusafw.com/0.10.3/release/api/com/asakusafw/runtime/core/Result.html]

5

com.asakusafw.runtime.testing.MockResult [https://docs.asakusafw.com/0.10.3/release/api/com/asakusafw/runtime/testing/MockResult.html]

コンテキストAPIを利用する演算子のテスト

テスト対象の演算子がコンテキストAPI 6 を利用する場合、コンテキストAPIが参照するバッチの起動引数をテスト側で指定します。

バッチ起動引数の指定は、 OperatorTestEnvironment クラスの setBatchArg メソッドで行います。 setBatchArg メソッドは第一引数に変数名、第二引数に変数の値を指定します。すべてのバッチ起動引数を指定したら、同クラスの reload メソッドで設定を有効化します。

演算子メソッドに対する操作は必ず reload メソッドの呼出し後に記述してください。

@Rule
public OperatorTestEnvironment env = new OperatorTestEnvironment();

@Test
public void sometest() {
    env.setBatchArg("key1", "value1");
    env.setBatchArg("key2", "value2");
    ...
    env.reload();

    // ここにテストを書く
}

6

コンテキストAPIについては、 Asakusa DSLユーザーガイド - コンテキストAPI を参照してください。

実行時プラグインを利用する演算子のテスト

テスト対象の演算子で実行時プラグイン 7 を利用する場合、「実行時プラグイン設定ファイル」が必要になります。これは利用する実行時プラグインや、それぞれのプラグインの設定を記述したもので、 OperatorTestEnvironment クラスをインスタンス化する際に位置を指定できます。

@Rule
public OperatorTestEnvironment env =
    new OperatorTestEnvironment("conf/asakusa-test-resources.xml");

ここに指定する位置は、クラスパス上の位置です。

引数を指定せずに OperatorTestEnvironment クラスをインスタンス化した場合には、クラスパスルートの asakusa-resources.xml というファイルを利用します。このファイルがない場合、最低限の設定のみを自動的に行います。

その他、 OperatorTestEnvironment クラスの configure メソッドを利用して個々のプラグインの設定を行うことも可能です。 configure メソッドは第一引数にプロパティ名、第二引数にプロパティの値を指定します。

演算子メソッドに対する操作は必ず reload メソッドの呼出し後に記述してください。

@Rule
public OperatorTestEnvironment env = new OperatorTestEnvironment(...);

@Test
public void sometest() {
    env.configure(
        "com.asakusafw.runtime.core.Report.Delegate",
        "com.asakusafw.runtime.core.Report$Default");
    ...
    env.reload();

    // ここにテストを書く
}

7

実行時プラグインについては、 実行時プラグインのデプロイ を参照してください。

DataLoader

演算子のいくつかは、入力データとしてデータモデルのリストを引数として受け取ります。 DataLoader 8 クラスは以下のようなデータ形式からデータモデルオブジェクトのリストを生成するユーティリティです。

Direct I/Oのデータフォーマットに対応するファイル (CSV, TSVファイルなど)

Direct I/O ユーザーガイド - データフォーマットの作成 に記載するデータフォーマットを指定することができます。

データ記述シート(Excelファイル)

テストドライバー用のデータ記述シート ( Excelによるテストデータ定義 ) を指定することができます。

Iterable ( List )

ビューAPIの入力データを Iterable や List から生成する場合に使用します。

以下は、Direct I/O CSV形式のCSVファイルを入力データとして使用するテストケースの実装例です。

public class CategorySummaryOperatorTest {

    @Rule
    public final OperatorTestEnvironment env = new OperatorTestEnvironment();

    @Test
    public void selectAvailableItem() {

        List<ItemInfo> candidates = env.loader(ItemInfo.class,
                ItemInfoCsvFormat.class,
                "item_info.csv" // (or) new File("src/test/resources/com/example/operator/item_info.csv")
        ).asList();

        CategorySummaryOperator operator = env.newInstance(CategorySummaryOperator.class);
        ItemInfo item1 = operator.selectAvailableItem(candidates, sales(1));
        ItemInfo item5 = operator.selectAvailableItem(candidates, sales(5));
        ...
    }
}

OperatorTestEnvironment の loader メソッドにデータモデルクラス、 DataFormat の実装クラス 9 、テストデータのファイルパスを指定して DataLoader を取得し、 asList メソッドでデータモデルオブジェクトのリストを取り出します。

ファイルパスを 文字列 で指定した場合はクラスパス上から検索し、 File オブジェクトで指定した場合は引数で指定したファイルパス(相対パス指定時は通常プロジェクトルートからの相対パス)を使用します。

8

com.asakusafw.testdriver.loader.DataLoader [https://docs.asakusafw.com/0.10.3/release/api/com/asakusafw/testdriver/loader/DataLoader.html]

9

DataFormat の実装クラスの作成方法は、 Direct I/O ユーザーガイド - データフォーマットの作成 に記載するドキュメントを参照してください

ビューAPIを使った演算子のテスト

ビューAPI を使った演算子のテストでは、 View<T> や GroupView<T> に対応するデータモデルオブジェクトを DataLoader を使って生成することができます。

以下は、テストデータ定義シート(Excelファイル)からビューAPIの入力データを設定するテストケースの実装例です。

public class WithViewOperatorTest {

    @Rule
    public final OperatorTestEnvironment env = new OperatorTestEnvironment();

    @Test
    public void updateWithView() {
        View<Foo> fooView = env.loader(Foo.class, "with_view.xls#foo")
                .asView();
        List<SalesDetail> salesList = env.loader(SalesDetail.class, "with_view.xls#sales")
                .asList();

        for (SalesDetail sales : salesList) {
            env.newInstance(WithViewOperator.class).updateWithView(sales, fooView);
            ...
        }
    }

    @Test
    public void extractWithGroupView() {
        GroupView<Foo> fooView = env.loader(Foo.class, "foo.xls#group_view")
                .group("store_code")
                .order("id")
                .asView();
        List<SalesDetail> salesList = env.loader(SalesDetail.class, "with_view.xls#sales")
                .asList();
        MockResult<SalesDetail> result = env.newResult(SalesDetail.class);
        MockResult<ErrorRecord> error = env.newResult(ErrorRecord.class);

        for (SalesDetail sales : salesList) {
            env.newInstance(WithViewOperator.class).extractWithGroupView(sales, fooView, result, error);
            ...
        }
    }
}

View<T> に対応するオブジェクトを取得するには、 DataLoader に対して asView メソッドを呼び出します。

GroupView<T> に対応するオブジェクトを取得するには、 DataLoader に対して group メソッドでグループを指定し、このメソッドが返す GroupLoader 10 に対して asView メソッドを呼び出します。

DataLoader で取得するデータに対して整列順序を指定したい場合は、上例のように order メソッドに整列化キーを指定します。

10

com.asakusafw.testdriver.loader.GroupLoader [https://docs.asakusafw.com/0.10.3/release/api/com/asakusafw/testdriver/loader/GroupLoader.html]

一時的なフロー記述に対するテスト

この方法は、演算子のテストを データフローのテスト と同様の方法で作成します。

このテストでは、テストドライバーを使って「一時的なフロー記述」（テスト専用のデータフロー）を作成し、そのデータフローにテスト対象の演算子を含めて実行するテストケースを記述します。テストデータのセットアップや実行結果の検証はテストドライバーの機能を利用します。

この方法は 演算子クラスに対するテスト と比べ、以下のようなメリットがあります。

複数の演算子を組み合わせたテストケースの作成が可能

複雑なテストデータ（入力データ、期待データ、テスト条件）を定義する様々な機能を利用可能

演算子とデータフローのテストを統一的な方法で記述することが可能

一時的なフロー記述を使ったテストケースの実装

一時的なフロー記述を使ったテストケースの実装方法は、基本的には後述の データフローのテスト で説明するテストドライバーを使ったデータフローのテストケースを作成する方法と同様です。以下、一時的なフロー記述を使った実装の固有部分について説明します。

データフローのテスト時には各 Tester クラスの runTest メソッドの引数に、フロー部品クラスのインスタンスやジョブフロークラス、バッチクラスのクラスオブジェクトを渡しますが、一時的なフロー記述ではFlow DSLのフロー記述メソッドと同様の形式 11 で「一時的なデータフロー」を記述します。

この場合 runTest メソッドの引数は Runnable 型になります。通常は以下例のように、ラムダ式としてフロー記述メソッドの内容を記述するとよいでしょう。

@Test
public void testWithTemporaryFlow() {
    // 入出力の定義
    FlowPartTester tester = new FlowPartTester(getClass());
    In<Hoge> in0 = tester.input("hoge", Hoge.class)
        .prepare("path/to/input0.xlsx");
    In<Foo> in1 = tester.input("foo", Foo.class)
        .prepare("path/to/input1.xlsx");
    Out<Bar> out = tester.output("bar", Bar.class)
        .verify(...);

    // テスト用の一時的なデータフローを構築して実行
    tester.runTest(() -> {
        HogeOperatorFactory f = new HogeOperatorFactory();
        Prepare op1 = f.prepare(in0);
        GetBars op2 = f.getBars(op1.out, in1);
        out.add(op2.out);
    });
}

11

Asakusa DSLユーザーガイド - Flow DSL の 「フロー記述メソッド」の項を参照

一時的なフロー記述を使ったテストのメリットとデメリット

一時的なフロー記述に対するテスト は 演算子クラスに対するテスト と比べて、一般的には以下のようなメリットやデメリットがあります。これらの点を考慮にいれて、演算子のテスト全体の構成を検討すべきでしょう。

メリット

複数の演算子を組み合わせたテストケースの作成

メソッドの実装を書かない演算子をテストの対象に含めたい場合や、複数の演算子が組み合わさって意味をなす場合など、テストケースに応じた任意の単位で演算子を組み合わせてデータフローを構築して演算子を実行し、その結果を評価することができます。

複数の演算子を組み合わせて大きな演算子を構築する、という仕組みはAsakusa DSLでは「フロー部品」の構築として提供していますが、フロー部品とは違った観点や粒度で演算子をテストしたいといった場合にも、この機能を利用することができます。

複雑なテストデータ（入力データ、期待データ、テスト条件）を持つテストケースの作成

テストドライバーには複雑なテストデータを定義する機能が豊富に提供されており、これらを利用することで効率良くテストケースを記述することが可能となります。

演算子とデータフローのテストを統一的な方法で記述

Asakusa DSLの各コンポーネントのテストをテストドライバーを利用したテストケースの記述に統一することで、テストケースの作成や管理が効率的になる可能性があります。

デメリット

テストケースの実装コスト

特にシンプルな演算子のテストケースを記述する場合は 演算子クラスに対するテスト に比べてテストケースの実装コストが高いでしょう。

テスト実行速度とマシンリソースへの負荷

テストドライバーの実行時には、テストケースに定義したデータフローから実行形式へのコンパイル、入出力データのセットアップなどの処理が行われます。このため、多くの場合 演算子クラスに対するテスト に比べてテストケースの実行に時間がかかり、マシンへの負荷は高くなるでしょう。

データフローのテスト

Flow DSL 12 を使って記述したデータフロー、およびBatch DSL 13 を使って記述したバッチに対するテストでは、DSLのコンパイラや実行環境と連携してテストを実行します。

Asakusa Frameworkはこの一連の処理を自動的に行うテストドライバーというモジュールを含んでいます。

テストドライバーはテスト対象の要素に対して、次の一連の処理を行います。

入力データを初期化する

入力データを流し込む

対象のプログラムをテスト用の実行エンジン向けにDSLコンパイルする

対象のプログラムを実行する

出力結果を取り込む

出力結果と期待データを検証する

12

Flow DSLについて詳しくは Asakusa DSLユーザーガイド - Flow DSL などを参照してください。

13

Batch DSLについて詳しくは Asakusa DSLユーザーガイド - Batch DSL などを参照してください。

テストデータの準備

テストドライバーでのテストを行うには、次の3種類の情報を用意します。これらをまとめて「テストデータ」と呼ぶことにします。

入力データ

それぞれのデータフローの入力に指定するデータセット。データモデルオブジェクトのリストと同じ構造。

期待データ

それぞれのデータフローからの出力に期待するデータセット。入力データと同じ構造。

テスト条件

それぞれの出力と期待データを比較して間違いを見つける方法。

テストドライバーはテストデータをさまざまな形式で記述できます。詳細は後述の テストデータの作成 にて説明します。

ここでは初めて利用する際に理解のしやすい Excelファイル形式 での準備方法を紹介します。

テストデータテンプレートの生成

テストデータをExcelで記述する場合、そのテンプレートを自動生成して利用します。このテンプレートはデータモデルごとに生成され、それぞれ次のようなシートが含まれます。

入力データシート

入力データを記述するシート。データモデルをシートの1行で表し、カラムごとにプロパティの値を記載できる。テンプレートではプロパティ名のヘッダのみが記載されている。

[入力データシートの例]

期待データシート

期待する出力データを記述するシート。入力データシートと同じ構造。

比較条件シート

出力結果データと期待データの比較条件を記述するシート。それぞれのプロパティをどのように比較するかをドロップダウン形式で選択できる。

[比較条件シートの例]

テストデータのテンプレートを生成するには、 Gradleを利用してテストデータテンプレート生成ツールを実行します。これはGradleの generateTestbook タスクで起動するので、プロジェクト内で以下のようにコマンドを実行します。

./gradlew generateTestbook

このコマンドを実行すると、プロジェクトの build/excel 配下に、DMDLで記述したそれぞれのデータモデルごとExcelのファイルが生成されます。このファイルには、上記の3種類のシートが含められます。

なお、このテンプレートはDMDLで記述されたデータモデルを元に作成しています。 DMDLの利用方法は DMDLスタートガイド を参照してください。

入力、期待データの作成

入力データを作成するには、生成したExcelファイルの input という名前のシートを編集します。このシートの1行目には、データモデルに定義したプロパティの名前が記載されているはずです。それぞれの行にオブジェクトごとのプロパティを入力してください。

期待データを作成するには、同様に output という名前のシートを編集して下さい。

Attention

セルを空にした場合、その値は null として取り扱われます。

Attention

文字列型のプロパティを編集する際には注意が必要です。数値、日付、論理値などの値を指定したセルや、空のセルは文字列として取り扱われません。これらの値を利用したい場合には、セルを ' から始めて文字列を指定してください。また、長さ0の文字列を入力したい場合には ' のみを指定してください。

テスト条件の記述

Excelファイルのテストデータテンプレートを利用する場合、出力データと期待データは次のように比較されます。

各レコードのキーとなるプロパティをもとに、出力データと期待データのペアを作る

出力と期待データのペアの中で、プロパティを条件に従って比較する

ペアを作れなかった出力データまたは期待データは、条件に従って比較する

上記の 1)キープロパティ、 2)プロパティの比較、 3)全体の比較 はそれぞれ生成したExcelファイルの rule という名前のシートで指定できます。

レコードのキーを指定する場合には、対象プロパティの「値の比較」という項目に 検査キー[Key] を選択します。キーとならないプロパティは、「値の比較」や「NULLの比較」にそれぞれ比較の条件を選択してください。

プロパティを比較しない場合には、「値の比較」に 検査対象外[-] を、「NULLの比較」に 通常比較[-] をそれぞれ選択します。

出力と期待データのペアを作れなかった場合の動作は、シート上部の「全体の比較」で選択します。

Excelファイルの配置

作成したExcelファイルは、クラスパスが通っているファイルパス上に配置します。

Asakusa Framework スタートガイド で作成したプロジェクトの構成では、 src/test/resources/<パッケージ> 以下にExcelファイル配置することを推奨します。

通常は テストクラスの作成 で作成するテストクラスと同じパッケージ上に配置するとよいでしょう。

テストクラスの作成

テストケースを記述するテストクラスを作成します。

Asakusa Framework スタートガイド で作成したプロジェクトの構成では、 src/test/java/<パッケージ> 以下にクラスファイルを配置することを推奨します。

通常は Excelファイルの配置 で配置するExcelファイルのパスと同じパッケージ上に配置するとよいでしょう。

フロー部品のテスト

フロー部品をテストするには、 FlowPartTester 14 を利用します。

@Test
public void testExampleAsFlowPart() {
    FlowPartTester tester = new FlowPartTester(getClass());
    In<Shipment> shipmentIn = tester.input("shipment", Shipment.class)
        .prepare("shipment.xls#input");
    In<Stock> stockIn = tester.input("stock", Stock.class)
        .prepare("stock.xls#input");
    Out<Shipment> shipmentOut = tester.output("shipment", Shipment.class)
        .verify("shipment.xls#output", "shipment.xls#rule");
    Out<Stock> stockOut = tester.output("stock", Stock.class)
        .verify("stock.xls#output", "stock.xls#rule");

    FlowDescription flowPart = new StockJob(shipmentIn, stockIn, shipmentOut, stockOut);
    tester.runTest(flowPart);
}

FlowPartTester をインスタンス化する際には、引数に getClass() を指定してテストケース自身のクラスを引き渡します。これは、先ほど配置したテストデータを検索するなどに利用しています。

FlowPartTester tester = new FlowPartTester(getClass());

データフローの入力を定義するには、 input メソッドを利用します。この引数には入力の名前 15 と、入力のデータモデル型を指定します。

input に続けて、 prepare 16 で入力データを指定します。 Excelファイル形式 の入力データシートを利用する場合は、入力データを定義したExcelシートのパスを以下のいずれかで指定します。

パッケージからの相対パス

クラスパスからの絶対パス ( / から始める )

上記の一連の結果を、 In<データモデル型> 17 の変数に保持します。

In<Shipment> shipmentIn = tester.input("shipment", Shipment.class)
    .prepare("shipment.xls#input");
In<Stock> stockIn = tester.input("stock", Stock.class)
    .prepare("stock.xls#input");

データフローの出力を定義するには、 output メソッドを利用します。この引数は入力と同様に名前とデータモデル型を指定します。

output に続けて、 verify 18 で期待データとテスト条件をそれぞれ指定します。指定方法は入力データと同様です。

出力の定義結果は、 Out<データモデル型> 19 の変数に保存します。

Out<Shipment> shipmentOut = tester.output("shipment", Shipment.class)
    .verify("shipment.xls#output", "shipment.xls#rule");
Out<Stock> stockOut = tester.output("stock", Stock.class)
    .verify("stock.xls#output", "stock.xls#rule");

入出力の定義が終わったら、フロー部品クラスを直接インスタンス化します。このときの引数には、先ほど作成した In<データモデル型> と Out<データモデル型> を利用してください。このインスタンスを runTest メソッドに渡すと、テストデータに応じたテストを自動的に実行します。

In<Shipment> shipmentIn = ...;
In<Stock> stockIn = ...;
Out<Shipment> shipmentOut = ...;
Out<Stock> stockOut = ...;
FlowDescription flowPart = new StockJob(shipmentIn, stockIn, shipmentOut, stockOut);
tester.runTest(flowPart);

14

com.asakusafw.testdriver.FlowPartTester [https://docs.asakusafw.com/0.10.3/release/api/com/asakusafw/testdriver/FlowPartTester.html]

15

ここの名前は他の名前と重複せず、アルファベットや数字のみで構成して下さい

16

com.asakusafw.testdriver.FlowDriverInput [https://docs.asakusafw.com/0.10.3/release/api/com/asakusafw/testdriver/FlowDriverInput.html]

17

com.asakusafw.vocabulary.flow.In [https://docs.asakusafw.com/0.10.3/release/api/com/asakusafw/vocabulary/flow/In.html]

18

com.asakusafw.testdriver.FlowDriverOutput [https://docs.asakusafw.com/0.10.3/release/api/com/asakusafw/testdriver/FlowDriverOutput.html]

19

com.asakusafw.vocabulary.flow.Out [https://docs.asakusafw.com/0.10.3/release/api/com/asakusafw/vocabulary/flow/Out.html]

ジョブフローのテスト

ジョブフローをテストするには、 JobFlowTester 20 を利用します。

@Test
public void testExample() {
    JobFlowTester tester = new JobFlowTester(getClass());
    tester.input("shipment", Shipment.class)
        .prepare("shipment.xls#input");
    tester.input("stock", Stock.class)
        .prepare("stock.xls#input");
    tester.output("shipment", Shipment.class)
        .verify("shipment.xls#output", "shipment.xls#rule");
    tester.output("stock", Stock.class)
        .verify("stock.xls#output", "stock.xls#rule");
    tester.runTest(StockJob.class);
}

利用方法は フロー部品のテスト とほぼ同様ですが、以下の点が異なります。

入出力の名前には、ジョブフローの注釈 Import や Export の name に指定した値を利用する

入出力を In や Out に保持しない

runTest メソッドにはジョブフロークラス( .class )を指定する

20

com.asakusafw.testdriver.JobFlowTester [https://docs.asakusafw.com/0.10.3/release/api/com/asakusafw/testdriver/JobFlowTester.html]

FlowPartTesterを使ったジョブフローのテスト

JobFlowTester を利用する場合、テスト実行時にジョブフローに定義しているインポータ記述、エクスポータ記述に基づいた外部連携モジュールが動作します。

この動作は外部システムと連携したテストを行うことができる一方で、テストドライバー実行環境に外部連携モジュールと接続する外部システムの設定が必要となります。例えばジョブフローがWindGate JDBCを利用する場合、WindGateが接続するデータベースの環境設定が必要になります。

ジョブフローのテストを行いたいが、外部連携モジュールとは接続せずにフロー記述メソッドの内容のみを検証したい、という場合があります。このような場合、 フロー部品のテスト で利用した FlowPartTester を使ってジョブフローのテストを行うこともできます。

FlowPartTester を使うことでテスト実行時のみジョブフローをフロー部品のように取り扱い、外部連携モジュールとの接続を行わずフロー記述メソッド部分のみを検証することができます。

バッチのテスト

バッチをテストするには、 BatchTester 21 を利用します。

@Test
public void testExample() {
    BatchTester tester = new BatchTester(getClass());
    tester.jobflow("stock").input("shipment", Shipment.class)
        .prepare("shipment.xls#input");
    tester.jobflow("stock").input("stock", Stock.class)
        .prepare("stock.xls#input");
    tester.jobflow("stock").output("shipment", Shipment.class)
        .verify("shipment.xls#output", "shipment.xls#rule");
    tester.jobflow("stock").output("stock", Stock.class)
        .verify("stock.xls#output", "stock.xls#rule");
    tester.runTest(StockBatch.class);
}

利用方法は ジョブフローのテスト とほぼ同様ですが、以下の点が異なります。

入出力を指定する前に、 jobflow メソッドを経由して入出力を利用するジョブフローのID 22 を指定する

runTest メソッドにはバッチクラス( .class )を指定する

21

com.asakusafw.testdriver.BatchTester [https://docs.asakusafw.com/0.10.3/release/api/com/asakusafw/testdriver/BatchTester.html]

22

注釈 @JobFlow の name に指定した文字列を利用して下さい

テストデータの作成

テストドライバーがサポートしているテストデータの形式には以下のようなものがあります。

Excelファイル形式

JSONファイル形式

Direct I/Oファイル形式 ( CSV, TSVファイルなど )

Javaクラス(オブジェクト)

テストデータの配置

Excelファイル形式 、 JSONファイル形式 、Direct I/Oファイル形式 で作成するテストデータ用のファイルは、クラスパスが通っているファイルパス上に配置します。通常はテストクラスと同じパッケージか、そのサブパッケージ上に配置します。

Asakusa Framework スタートガイド などの手順でプロジェクトテンプレートから作成したプロジェクトでは src/test/resources 配下にファイルを配置することを推奨しています。

複数のテストから利用されるテストデータを、任意のパッケージに配置することもできます。この場合テストデータの指定時に、クラスパスからの絶対パスを指定する必要があります。

Excelファイル形式

Asakusa FrameworkではExcelファイル形式でテストデータを定義するための、以下のようなツールを提供しています。

DMDLスクリプトのデータモデル定義に対応する、テストデータ定義用のテンプレートを生成するコマンドラインツール

Excelシート上にデータフローの入力データ、期待データを定義するデータ記述シート

Excelシート上に詳細なテスト条件（出力結果データと期待データの比較条件）を定義する比較条件シート

これらの基本的な使い方については、先述の テストデータの準備 を参考にしてください。各ツールの詳細は、以下のドキュメントを参照してください。

Excelによるテストデータ定義

Excelファイルをテストドライバーで使用する

作成したExcelファイルをテストドライバーで使用するには、 各 Tester クラスの input.prepare() メソッドや output.verify() メソッドの各引数に、 <ファイルパス>#<シート名> を指定します。

In<Shipment> shipmentIn = tester.input("shipment", Shipment.class)
    .prepare("shipment.xls#input");
In<Stock> stockIn = tester.input("stock", Stock.class)
    .prepare("stock.xls#input");

Out<Shipment> shipmentOut = tester.output("shipment", Shipment.class)
    .verify("shipment.xls#output", "shipment.xls#rule");
Out<Stock> stockOut = tester.output("stock", Stock.class)
    .verify("stock.xls#output", "stock.xls#rule");

テストクラスと同じパッケージにExcelファイルを配置した場合は、ファイルパス部分はファイル名のみを指定します。

サブパッケージ a.b などに配置した場合には、 a/b/file.xls#hoge のようにパスを / で区切って指定します。

複数のテストから共通のテストデータとして利用する目的などで、任意のパッケージ上に配置した場合は、/x/y/file.xls#fuga のようにパスの先頭に / から始まるパスを指定します。

JSONファイル形式

入力データと期待データを、JSONファイルを読み込んで生成することができます。

現在のところ、JSON形式でテスト条件を記述することはできません。 Excelファイル形式 の比較条件シートを使用するか、Javaクラス(オブジェクト) で説明する方法でテスト条件を定義してください。

JSON形式によるテストデータ定義の詳細は、以下のドキュメントを参照してください。

JSONによるテストデータ定義

JSONファイルをテストドライバーで使用する

作成したJSONファイルをテストドライバーで使用するには、 各 Tester クラスの input.prepare() メソッドや output.verify() メソッドの各引数に、 <ファイルパス> を指定します。

ただし、テスト条件はJSONファイルで定義することができないので、他の形式で作成したファイルなどを指定します。

In<Shipment> shipmentIn = tester.input("shipment", Shipment.class)
    .prepare("shipment_input.json");
In<Stock> stockIn = tester.input("stock", Stock.class)
    .prepare("stock_input.json");

Out<Shipment> shipmentOut = tester.output("shipment", Shipment.class)
    .verify("shipment_output.json", "shipment.xls#rule");
Out<Stock> stockOut = tester.output("stock", Stock.class)
    .verify("stock_output.json", "stock.xls#rule");

その他、ファイルパスの指定方法は Excelファイルをテストドライバーで使用する と同様です。

Direct I/Oファイル形式

入力データと期待データを、Direct I/Oが取り扱うことができるフォーマットファイルを読み込んで生成することができます。

この機能を使うことで、CSV形式やTSV形式など、Direct I/Oが対応する様々なフォーマットファイルをテストデータとして利用することが可能になります。

現在のところ、Direct I/Oファイル形式でテスト条件を記述することはできません。 Excelファイル形式 の比較条件シートを使用するか、Javaクラス(オブジェクト) で説明する方法でテスト条件を定義してください。

Direct I/Oファイルをテストドライバーで使用する

作成したDirect I/Oファイルをテストドライバーで使用するには、 各 Tester クラスの input.prepare() メソッドや output.verify() メソッドの各引数に、 DataFormat の実装クラス 23 と <ファイルパス> を指定します。

ただし、テスト条件はDirect I/Oファイルで定義することができないので、他の形式で作成したファイルなどを指定します。

以下は、Direct I/O CSV 形式のCSVファイルを入力データ、期待データに指定する実装例です。

tester.input("storeInfo", StoreInfo.class).prepare(
        StoreInfoCsvFormat.class,
        "store_info.csv");
tester.input("itemInfo", ItemInfo.class).prepare(
        ItemInfoCsvFormat.class,
        "item_info.csv");
tester.input("salesDetail", SalesDetail.class).prepare(
        SalesDetailCsvFormat.class,
        new File("src/test/resources/com/example/jobflow/2011-04-01.csv"));

tester.output("categorySummary", CategorySummary.class).verify(
        CategorySummaryCsvFormat.class,
        "result.csv",
        "summarize.xls#result_rule");
tester.output("errorRecord", ErrorRecord.class).verify(
        ErrorRecordCsvFormat.class,
        "error/2011-04-01.csv",
        "error.xls#result_rule");

ファイルパスを 文字列 で指定した場合はクラスパス上から検索し、 File オブジェクトで指定した場合は引数で指定したファイルパス(相対パス指定時は通常プロジェクトルートからの相対パス)を使用します。

23

DataFormat の実装クラスの作成方法は、 Direct I/O ユーザーガイド - データフォーマットの作成 に記載するドキュメントを参照してください

入出力データの変換

Experimental

Asakusa Framework バージョン 0.10.3 では、入出力データの変換機能は試験的機能として提供しています。

各 Tester クラスの input.prepare() メソッドや output.verify() メソッドで指定するテストデータファイルから入出力データを構築する際に、そのデータモデルの内容を変換する処理を挿入することができます。

入力データに対してこの変換処理を適用するには prepare メソッドの第二引数( Direct I/Oファイルをテストドライバーで使用する を使う場合は第三引数)に、期待データに対して変換処理を適用するには verify に続いて transform メソッドに変換ロジックを記述したラムダ式を指定します。

In<Hoge> inHoge = tester.input("inHoge", Hoge.class).prepare(
        "hoge.xls#sum_in",
        hoge -> hoge.setFoo(hoge.getFoo() + 1)
);
Out<Hoge> outHoge = tester.output("outHoge", Hoge.class).verify(
        "hoge.xls#sum_out",
        "hoge.xls#rule"
        ).transform(hoge -> hoge.setBarAsString("test")
);

Javaクラス(オブジェクト)

ここではテストデータをJavaで記述する方法について紹介します。

入力データと期待データをJavaで記述する

入力データや期待データをJavaで定義するには、テストドライバーAPIの input.prepare() メソッドや output.verify() メソッドでテスト対象となるデータモデル型のデータモデルオブジェクトを保持するコレクション( Iterable<データモデル型> )を指定します。

List<Shipment> shipments = new ArrayList<Shipment>();

Shipment ship1 = new Shipment();
ship1.setItemCode(1001);
ship1.setShippedDate(DateTime.valueOf("20110102000000", Format.SIMPLE));
shipments.add(ship1)

Shipment ship2 = new Shipment();
ship2.setItemCode(1002);
ship2.setShippedDate(DateTime.valueOf("20110103000000", Format.SIMPLE));
shipments.add(ship2)

In<Shipment> shipmentIn = tester.input("shipment", Shipment.class)
    .prepare(shipments);

テスト条件をJavaで記述する

テスト条件は期待データと実際の結果を突き合わせるためのルールを示したもので、Javaで直接記述することも可能です。

テスト条件をJavaで記述するには、 ModelVerifier 24 インターフェースを実装したクラスを作成します。このインターフェースには、2つのインターフェースメソッドが定義されています。

Object getKey(T target)

指定のオブジェクトから突き合わせるためのキーを作成して返す。キーは Object.equals() を利用して突き合わせるため、返すオブジェクトは同メソッドを正しく実装している必要がある。

Object verify(T expected, T actual)

突き合わせた2つのオブジェクトを比較し、比較に失敗した場合にはその旨のメッセージを返す。成功した場合には null を返す。

ModelVerifier インターフェースを利用したテストでは、次のように期待データと結果の比較を行います。

それぞれの期待データから getKey(期待データ) でキーの一覧を取得する

それぞれの結果データから getKey(結果データ) でキーの一覧を取得する

期待データと結果データから同じキーになるものを探す

見つかれば veriry(期待データ, 結果データ) を実行する

期待データに対する結果データが見つからなければ、 verify(期待データ, null) を実行する

結果データに対する期待データが見つからなければ、 verify(null, 結果データ) を実行する

いずれかの verify() が null 以外を返したらテストは失敗となる

全ての verify() が null を返したら、次の出力に対する期待データと結果データを比較する

以下は ModelVerifier インターフェースの実装例です。 category, number という2つのプロパティから複合キーを作成して、突き合わせた結果の value を比較しています。また、期待データと結果データの個数が違う場合はエラーにしています。

class ExampleVerifier implements ModelVerifier<Hoge> {
    @Override
    public Object getKey(Hoge target) {
        return Arrays.asList(target.getCategory(), target.getNumber());
    }

    @Override
    public Object verify(Hoge expected, Hoge actual) {
        if (expected == null || actual == null) {
            return "invalid record";
        }
        if (expected.getValue() != actual.getValue()) {
            return "invalid value";
        }
        return null;
    }
}

ModelVerifier を実装したクラスを作成したら、各 Tester クラスの output.verify() メソッドの第二引数に指定します。

@Test
public void testExample() {
    JobFlowTester tester = new JobFlowTester(getClass());
    tester.input("shipment", Shipment.class)
        .prepare("shipment.xls#input");
    tester.output("hoge", Hoge.class)
        .verify("hoge.json", new ExampleVerifier());
    ...
}

24

com.asakusafw.testdriver.core.ModelVerifier [https://docs.asakusafw.com/0.10.3/release/api/com/asakusafw/testdriver/core/ModelVerifier.html]

テスト条件をJavaで拡張する

テスト条件をJavaで記述する で説明した方法ではテスト条件をすべてJavaで記述しますが、Excelなどで記述したテスト条件をJavaで拡張することもできます。

テスト条件をJavaで拡張するには、 ModelTester 25 インターフェースを実装したクラスを作成します。このインターフェースは先述の ModelVerifier の親インターフェースとして宣言されており、以下のインターフェースメソッドが定義されています。

Object verify(T expected, T actual)

突き合わせた2つのオブジェクトを比較し、比較に失敗した場合にはその旨のメッセージを返す。成功した場合には null を返す。

ModelTester インターフェースを利用したテストでは、次のように期待データと結果の比較を行います。

Excel等で記述したテスト条件で期待データと結果データの突き合わせと比較を行う

上記で突き合わせに成功したら、 ModelTester.verify(<期待データ>, <結果データ>) で比較を行う

両者の比較のうちいずれかに失敗したらテストは失敗となる

以下は ModelTester インターフェースの実装例です。

class ExampleTester implements ModelTester<Hoge> {

    @Override
    public Object verify(Hoge expected, Hoge actual) {
        if (expected == null || actual == null) {
            return "invalid record";
        }
        if (expected.getValue() != actual.getValue()) {
            return "invalid value";
        }
        return null;
    }
}

ModelTester を実装したクラスを作成したら、各 Tester クラスの output.verify() メソッドの第三引数にそのインスタンスを指定します 26 。

@Test
public void testExample() {
    JobFlowTester tester = new JobFlowTester(getClass());
    tester.input("shipment", Shipment.class)
        .prepare("shipment.xls#input");
    tester.output("hoge", Hoge.class)
        .verify("hoge.json", "hoge.xls#rule", new ExampleTester());
    ...
}

Hint

ModelTester のインスタンスを指定する代わりに、比較ロジックを記述したラムダ式を指定することもできます。

テスト条件の拡張は、主にExcelなどで表現しきれない比較を行いたい場合に利用できます。比較方法をすべてJavaで記述する場合には テスト条件をJavaで記述する の方法を参照してください。

25

com.asakusafw.testdriver.core.ModelTester [https://docs.asakusafw.com/0.10.3/release/api/com/asakusafw/testdriver/core/ModelTester.html]

26

第三引数を指定できるのは、テスト条件をパスで指定した場合のみです。 ModelVerifier を利用する場合には指定できません。

テスト実行時の設定

ここではテストドライバーでテスト実行時の環境や動作を設定するための機能を説明します。

コンテキストAPIを利用するデータフローのテスト

テスト対象のデータフローでコンテキストAPIを利用している場合、コンテキストAPIが参照するバッチの起動引数をテスト側で指定します。この設定には、 各 Tester クラスの setBatchArg というメソッドから設定します。

@Test
public void testExample() {
    BatchTester tester = new BatchTester(getClass());
    tester.setBatchArg("message", "Hello, world!");
    ...
}

上記のように、第一引数には変数名、第二引数には変数の値を指定します。

なお、データフローのテストでは コンテキストAPIを利用する演算子のテスト で必要な reload の指定は不要です。

実行時プラグインを利用するデータフローのテスト

テスト対象の演算子で実行時プラグイン 27 を利用する場合、「実行時プラグイン設定ファイル」が必要になります。データフローのテストの際には、利用している開発環境にインストールされた設定ファイル 28 を利用して処理を実行します。

その他、各 Tester クラスの configure メソッドを利用して個々のプラグインの設定を行うことも可能です。

@Test
public void testExample() {
    BatchTester tester = new BatchTester(getClass());
    tester.configure(
        "com.asakusafw.runtime.core.Report.Delegate", "com.example.CustomReportDelegate"
    );
    ...
}

上記のように、第一引数にはプロパティ名、第二引数にはプロパティの値を指定します。

なお、データフローのテストでは 実行時プラグインを利用する演算子のテスト で必要な reload の指定は不要です。

Attention

実行時プラグインはの設定は、Hadoop起動時の “-D” オプションで指定するプロパティをそのまま利用しています。そのため、 configure メソッドでHadoopのプロパティを利用することも可能ですが、通常の場合は利用しないでください。

27

実行時プラグインのデプロイ を参照

28

Asakusa Gradle Plugin ユーザーガイド の手順に従って作成したプロジェクトでは $ASAKUSA_HOME/core/conf/asakusa-resources.xml が配置されるため、デフォルトの状態ではこのファイルが利用されます。デフォルトの状態では演算子のテストで使用される実行時プラグイン設定ファイルと異なるファイルが利用されることに注意してください。

テストドライバーの各実行ステップをスキップする

テストドライバーは、各ステップをスキップするためのメソッドが提供されています。これらのメソッドを使用することで、以下のようなことが可能になります。

入力データ設定前にクリーニング、および入力データの投入をスキップして既存データに対するテストを行う

出力データの検証をスキップしてテストドライバーAPIの外側で独自のロジックによる検証を行う。

スキップを行う場合、 Tester クラスが提供する以下のメソッドを利用します。

void skipValidateCondition(boolean skip)

テスト条件の検証をスキップするかを設定する。

void skipCleanInput(boolean skip)

入力データのクリーニング(truncate)をスキップするかを設定する。

void skipCleanOutput(boolean skip)

出力データのクリーニング(truncate)をスキップするかを設定する。

void skipPrepareInput(boolean skip)

入力データのセットアップ(prepare)をスキップするかを設定する。

void skipPrepareOutput(boolean skip)

出力データのセットアップ(prepare)をスキップするかを設定する。

void skipRunJobFlow(boolean skip)

ジョブフローの実行をスキップするかを設定する。

void skipVerify(boolean skip)

テスト結果の検証をスキップするかを設定する。

その他のオプション

その他、各 Tester クラスで利用可能なテストの動作を設定するメソッドは以下の通りです。

setExtraCompilerOption(String name, String value)

テストドライバー実行時にアプリケーションをコンパイルする際のコンパイラオプションを設定する。

テストのデバッグと実行結果の分析

ここではテストドライバーを使ったテストのデバッグや実行結果の分析に利用できる補助機能について説明します。

データフローの出力結果を保存する

テスト実行時のデータフローの出力結果をファイルに保存するには、各 Tester クラスの output() に続いて dumpActual("<出力先>") を指定します。

出力先には、ファイルパスや File 29 オブジェクトを指定できます。ファイルパスで相対パスを指定した場合、テストを実行したワーキングディレクトリからの相対パス上に結果が出力されます。

出力先に指定したファイル名の拡張子に応じた形式で出力が行われます。標準ではExcelシートを出力する .xls または .xlsx を指定できます。

Out<Shipment> shipmentOut = tester.output("shipment", Shipment.class)
    .dumpActual("build/dump/actual.xls")
    .verify("shipment.xls#output", "shipment.xls#rule");

また、Direct I/Oが取り扱うことができるフォーマットファイルで出力することもできます。この場合、Direct I/Oファイルをテストドライバーで使用する と同様に DataFormat の実装クラスと File オブジェクトを指定します。

Out<ErrorRecord> errorRecord = tester.output("errorRecord", ErrorRecord.class)
    .dumpActual(ErrorRecordCsvFormat.class, new File("build/dump/error-record.csv")
    .verify("error.xls#output", "error.xls#rule");

この操作は上記例のように verify() と組み合わせて利用することができます。

Attention

EclipseなどのIDEを利用している場合、ファイルが出力された後にワークスペースの表示更新やリフレッシュなどを行うまで、出力されたファイルが見えない場合があります。

29

java.io.File

テスト実行の比較結果を保存する

テストドライバーに設定した期待データとテスト実行結果との比較結果をファイルに保存するには、対象の出力に対して dumpDifference(<出力先>) を指定します。

Out<Shipment> shipmentOut = tester.output("shipment", Shipment.class)
    .verify("shipment.xls#output", "shipment.xls#rule")
    .dumpDifference("build/dump/difference.html");

データフローの出力結果を保存する と同様に、出力先にはファイルパスや File オブジェクトを指定できます。ファイルパスで相対パスを指定した場合、テストを実行したワーキングディレクトリからの相対パス上に結果が出力されます。

また、出力先に指定したファイル名の拡張子に応じた形式で出力が行われます。標準ではHTMLファイルを出力する .html を指定できます。

この操作は、 verify() と組み合わせて指定してください。 verify() の指定がない場合、比較結果の保存は行われません。また、比較結果に差異がない場合には比較結果は保存されません。

演算子のトレースログを出力する

テスト対象のデータフローに含まれる演算子について、入力されたデータと出力されたデータを調べるには、テストドライバーのトレース機能を利用すると便利です。トレース機能を利用すると、指定した演算子に入力されたデータや出力されたデータを レポートAPI 経由で表示できます。

トレース機能はユーザー演算子に指定することができます。コア演算子にはトレースを指定することはできません。

入力データのトレース

演算子に入力されたデータを調べる場合、各 Tester クラスの addInputTrace メソッドを利用して対象の演算子と入力ポートを指定します。下記の例は、演算子クラス YourOperator に作成した演算子メソッド operatorName の入力ポート 30 inputName に入力される全てのデータについてトレースの設定を行います。

@Test
public void testExample() {
    JobFlowTester tester = new JobFlowTester(getClass());
    tester.addInputTrace(YourOperator.class, "operatorName", "inputName");
    ...
}

30

演算子ファクトリクラスに含まれる演算子ファクトリメソッドの引数名が入力ポート名に該当します。詳しくは Asakusa DSLユーザーガイド - 演算子ファクトリ を参照してください。

出力データのトレース

演算子から出力されたデータを調べる場合、各 Tester クラスの addOutputTrace メソッドを利用して対象の演算子と出力ポートを指定します。下記の例は、演算子クラス YourOperator に作成した演算子メソッド operatorName の出力ポート 31 outputName から出力する全てのデータについてトレースの設定を行います。

@Test
public void testExample() {
    JobFlowTester tester = new JobFlowTester(getClass());
    tester.addOutputTrace(YourOperator.class, "operatorName", "outputName");
    ...
}

31

演算子ファクトリクラスに含まれる演算子オブジェクトクラスのフィールド名が出力ポート名に該当します。詳しくは Asakusa DSLユーザーガイド - 演算子ファクトリ を参照してください。

トレース情報の出力

上記の設定を行った状態でテストを実行すると、指定した演算子の入力や出力が行われるたびに、文字列 TRACE- を含むメッセージを レポートAPI 経由で出力します 32 。ここには、トレースを設定した対象の情報や、実際に入出力が行われたデータの内容が含まれています。

Attention

トレース機能を有効にすると、テストの実行に非常に時間がかかるようになる場合があります。

Note

トレースの出力方式は将来変更される可能性があります。

32

このとき、 Report.info() を利用してメッセージを出力しています。メッセージが正しく表示されない場合には、Report APIの設定を確認してください。

テストドライバー実行環境

テストドライバーを使ったテストを実行する上で必要となる環境について説明します。

Asakusa Frameworkのインストール

テストドライバーを実行する環境には開発環境用のAsakusa Frameworkをインストールしておく必要があります。

開発環境用のAsakusa Frameworkをインストールする手順については、以下のドキュメントなどを参照してください。

Asakusa Framework スタートガイド - Asakusa Frameworkのインストール

Windows用の実行ライブラリ

Windows上でテストドライバーを利用する場合、環境にVisual C++ 2010 ランタイム ライブラリがインストールされている必要があります。

環境にこのライブラリがインストールされていない場合、以下のサイトなどからライブラリを入手し、環境にインストールしてください。

Microsoft Visual C++ 2010 再頒布可能パッケージ (x64) [https://www.microsoft.com/ja-jp/download/details.aspx?id=14632]

Note

Visual C++ 2010 ランタイム ライブラリがインストールされていない環境上でテストを実行すると、以下のようなエラーメッセージが表示されテストの実行が失敗します。

java.lang.IllegalStateException: ExitCodeException exitCode=-1073741515:
...
Caused by:
        ExitCodeException exitCode=-1073741515:

Tip

Visual C++ 2010 ランタイム ライブラリは様々なソフトウェアに含まれるため、既にインストール済みになっている場合も多くあります。

インテグレーションテスト

ここではバッチアプリケーションのインテグレーションテストを行ういくつかの方法と、テストツールの利用方法などについて説明します。

テスト方法とツール

バッチアプリケーションのインテグレーションテストを行うには、以下のような方法があります。

YAESS を利用してアプリケーションを実行する

Asakusa CLI を利用してアプリケーションを実行する

バッチテストランナー を利用してアプリケーションを実行する

テストツールタスク を利用してアプリケーションを実行する

YAESS

YAESSを利用する方法では、運用環境と同様の手順でバッチアプリケーションを実行するため、運用環境に近い確実なテストが行えます。

その反面、各実行環境に応じた適切な設定を管理する必要があったり、標準の設定では運用環境を前提とした詳細なログが出力されたりと、開発環境上でちょっとした動作確認を行うにはやや煩雑です。

Asakusa CLI

Asakusa CLI ( asakusa run ) を利用する方法は、開発環境や運用環境で簡易的にバッチアプリケーションの動作確認を行う場合に適しています。

アプリケーション情報の表示、およびDSL情報の可視化機能と統合したコマンドラインインターフェース、シンプルな設定、簡易的なログ出力などにより、簡単にすばやくバッチアプリケーションを実行し、その結果を確認、分析することができます。ただしYAESSのような実行時の細かい設定を管理することはできません。

バッチテストランナー

バッチテストランナーは、テストドライバーの内部機構を利用して簡易的にバッチアプリケーションを実行するAPIです。コマンドラインインターフェースとしても利用することができます。テストドライバーと同様に、ローカルコンピューター上のAsakusa Framework実行環境を利用してバッチを実行します。

複雑な自動テストを構築するための各種インターフェースとして利用するとよいでしょう。 YAESSのような細かい実行設定を行うことはできないので、テスト実行以外の用途では利用すべきではありません。

テストツールタスク

テストツールタスクはテストドライバーやバッチテストランナーが持つ機能を組み合わせてGradleのタスクとして実行できるようにするものです。 YAESSやバッチテストランナーを使ってアプリケーションを実行しつつ、データ配置やデータの検証はテストドライバーの機構を利用する、という場合に利用することができます。

テストツールタスクはインテグレーションテストの自動化を行う場合や、自動テストと手動テストを組み合わせるような場合などで利用することを想定しています。

以下はツールごとにおける自動化部分の比較です。

ツールごとのインテグレーションテスト自動化部分の比較

項目

テストドライバー

バッチテストランナー

テストツールタスク

アプリケーションのビルド

○

×

×

アプリケーションのデプロイ

○

×

×

入力データの配置

○

×

○

アプリケーションの実行

○

○

○

実行結果の確認

○

×

○

バッチテストランナー

バッチテストランナーはテストドライバーが持つ機能のうち、アプリケーションの実行のみを単独で行えるようにしたものです。テストドライバーが自動的に行っていたいくつかの部分について、手動で細やかな設定を行えるようになります。

バッチテストランナーを利用してアプリケーションを実行するには、バッチテストランナーのプログラミングインターフェースや、コマンドラインインターフェースを利用します。詳しくは以降を参照してください。

Hint

バッチテストランナーが自動的に行わない部分の手順については、 サンプルアプリケーションの実行 などを参照してください。

プログラミングインターフェース

Javaのプログラムからバッチテストランナーを実行するには、 com.asakusafw.testdriver.tools.runner.BatchTestRunner 33 クラスを利用します。詳しい利用方法は、Javadocを参照してください。

以下は Asakusa Framework スタートガイド で紹介しているサンプルアプリケーションを実行する例です。

int result = new BatchTestRunner("example.summarizeSales")
    .withArgument("date", "2011-04-01")
    .execute();

if (result != 0) {
    // エラー処理 ...
}

33

com.asakusafw.testdriver.tools.runner.BatchTestRunner [https://docs.asakusafw.com/0.10.3/release/api/com/asakusafw/testdriver/tools/runner/BatchTestRunner.html]

コマンドラインインターフェース

コマンドラインからバッチテストランナーを実行するには、テストドライバーのクラスライブラリ群をクラスパスに登録した状態で com.asakusafw.testdriver.tools.runner.BatchTestRunner クラスを実行します。

指定できるオプションは次の通りです。

-b,--batch <batch_id>

実行するバッチのバッチIDを指定します。

-A,--argument <name=value>

実行するバッチのバッチ引数を指定します。

-D,--property <name=value>

実行時プラグインを利用するデータフローのテスト を行います。

例えば Asakusa Framework スタートガイド で紹介しているサンプルアプリケーションを実行する場合のオプション指定は以下のようになります。

-b example.summarizeSales -A date=2011-04-01

コマンドラインインターフェースは、バッチアプリケーションが正常終了した際に終了コード 0 を返し、正常終了しなかった場合に非 0 を返します。

テストツールタスク

テストツールタスクはテストドライバーやバッチテストランナーが持つ機能を組み合わせてGradleのタスクとして実行できるようにするものです。バッチの実行にはYAESSとバッチテストランナーのどちらかを選択します。

以下にテストツールタスクを使って作成したGradleタスクの例を示します。

task batchTestSummarize(type: com.asakusafw.gradle.tasks.TestToolTask) {
    clean description: 'com.example.batch.SummarizeBatch'
    prepare importer: 'com.example.jobflow.StoreInfoFromCsv',
        data: '/com/example/jobflow/masters.xls#store_info'
    prepare importer: 'com.example.jobflow.ItemInfoFromCsv',
        data: '/com/example/jobflow/masters.xls#item_info'
    prepare importer: 'com.example.jobflow.SalesDetailFromCsv',
        data: '/com/example/jobflow/summarize.xls#sales_detail'
    run batch: 'example.summarizeSales'
    verify exporter: 'com.example.jobflow.CategorySummaryToCsv',
        data: '/com/example/jobflow/summarize.xls#result',
        rule: '/com/example/jobflow/summarize.xls#result_rule'
}

See also

TestToolTask や Gradleの利用方法については Asakusa Gradle Plugin ユーザーガイド を参照してください。

Excelによるテストデータ定義

この文書では、Excelでテストデータを定義する方法や、テストデータのテンプレートを生成する方法について紹介します。

テストデータテンプレート

テストデータはDMDLで記述したそれぞれのデータモデルに対して記述します。 Asakusa Frameworkには、このテストデータを記述するためのExcelテンプレートを生成するツールが同梱されています。

See also

DMDLでデータモデルを定義する方法は、 アプリケーションの実装 - Asakusa Data Model を参照してください。

テストデータテンプレートの生成

テストデータのテンプレートを生成するには、 Gradleを利用してテストデータテンプレート生成ツールを実行します。これはGradleの generateTestbook タスクで起動するので、プロジェクト内で以下のようにコマンドを実行します。

./gradlew generateTestbook

このコマンドを実行すると、プロジェクトの build/excel 配下に、DMDLで記述したそれぞれのデータモデルごとにExcelのファイルが生成されます。このファイルには、以下のシートが含められます。

入力データと期待データ 定義用のデータ記述シート

テスト条件 定義用の比較条件シート

入力データと期待データ

入力データと期待データは、それぞれ生成したテストデータテンプレートのデータ記述シートに記述します。このデータ記述シートは、下図のように1行目にプロパティ名の一覧が記載され、2行目以降が空のシートです。

それぞれの行はデータモデルオブジェクト一つ分を表しています。それぞれの列はオブジェクトのプロパティを表し、1行目にそのプロパティの名前が記載されています。そのため、それぞれのセルは特定のオブジェクトのプロパティ値を表すことになります。

Hint

プロパティが不要である場合、その列は削除してしまってかまいません。削除した場合、そのプロパティは NULL として取り扱います。

NULL値

NULLを表す値を入力するには、そのセルを空のままにします。ここでは空の文字列とNULLは明確に区別されており、セルの種類が文字列であっても、空のセルは常にNULLとして取り扱います。

数値

数値を表す値を入力するには、セルにその数値を入力するか、またはその数値を表す文字列を入力します。

文字列が入力された場合、次の方法で適切な数値に変換します。

数値の変換方法

データ型

変換方法

long までの整数

Long.parseLong

double までの浮動小数点

Double.parseDouble

上記以外の数値

new BigDecimal(...)

その後、実際の型に合わせて値が切り詰められます。値が切り詰められる際に、オーバーフローやアンダーフローが発生する場合もあります。

Attention

パーセンテージや日付等で表されているセルについても、Excelでは内部的に数値で表現されています。このため、数値を表すプロパティに対してこれらの値を入力した場合、予期せぬ値として評価されてしまう場合があります。

Hint

Excelは数値データを内部的に倍精度の浮動小数点数として保持するようです。絶対値の大きな値や、正確な固定小数点数を利用したい場合には、文字列として入力するのが無難です。

論理値

論理値を表す値を入力するには、セルに TRUE または FALSE を直接指定するか、またはそれらと同等の文字列を入力します。文字列でこれらの値を指定した場合、文字列 TRUE または FALSE と大文字小文字の区別なしに一致すれば、その値として取り扱います。

日付と時刻

日付や時刻を表す値を入力するには、セルに日時（日付と時刻）を指定します。

テストドライバーは内部的に日付のみ、時刻のみ、日時、の3種類のデータ型を提供していますが、Excelでは指定できる形式は日時のみです。日時以外のプロパティに対しては、必要なフィールドのみから値を取り出します 1 。

Note

ここは本来文字列による指定も可能であるべきですが、現在はExcelの日付や時刻に関する形式のみをサポートしています。

1

つまり、日付型に 1999-12-31 12:34:56 という日時が指定されていても、実際には1999年12月31日を表す日付データとして取り扱われます。

文字列

文字列を入力するには、セルにその文字列を指定します。ただし、Excelのセルは文字列を入力したつもりでも、内部的に数値や日付などの別の形式に変換されてしまう場合があります。

Attention

テスト時のミスを減らすため、文字列型のプロパティに対応するセルに文字列型以外を入力した場合、テストは失敗するようになっています。文字列型以外のセルには、たとえば数値や日付など、ここまでに紹介したデータ型が含まれます。

Excelのセルの形式を強制的に文字列として指定するには、セルに入力する値の先頭に ' (シングルクウォート) を付与します。このシングルクウォート記号は文字列に含まれず、以降の値が文字列として取り扱われます。

また、空のセルはテストドライバーによって NULL値 として取り扱われます。長さ0の文字列を入力したい場合には ' のみを指定してください。

数式

値にはExcelの数式を指定することができます。数値内にセル参照を指定することも可能です。

Hint

テストドライバーでは数式の評価や実行に Apache POI [http://poi.apache.org/] の機能を利用しています。利用可能な数式やその制限などについては Apache POI [http://poi.apache.org/] の情報を確認してください。

テスト条件

テスト条件は、生成したテストデータテンプレートの比較条件シートに記述します。このシートは、全体の比較条件やプロパティごとの比較条件をドロップダウンの形式で選択します。

このシートは、2行目で 全体の比較条件 を指定し、4行目以降でプロパティごとの比較条件を指定します。また、4行目移行は1列目(A)に対象のプロパティ名が記載されています。

Format

条件記述シートにはテストデータテンプレートのフォーマットバージョンが定義されており、このバージョンによって利用可能な機能が異なります。

特定バージョンから利用可能な機能は後述の各機能の説明においてその条件が記載されています。

フォーマットバージョンの一覧は以下の通りです。

フォーマットバージョン

バージョン

Frameworkバージョン 2

主な変更点

EVR-1.0.0

0.2.0 以降

初期バージョン

EVR-2.0.0

0.7.0 以降

値の比較 に 特殊ルール [Expr] を追加

Attention

テストデータテンプレートのフォーマットバージョンを上げたい場合は、新規のテストデータテンプレートを作成し、テスト条件シートを再定義してください。

なお、入力データと期待データのシートはフォーマットバージョンのようなバージョン指定はありません。

2

該当するフォーマットバージョンが利用可能なAsakusa Frameworkのバージョンです。テストデータテンプレートの生成を行った場合、そのAsakusa Frameworkが対応している最新のフォーマットバージョンを持つテンプレートが生成されます。

テストドライバーの動作

テストドライバーは、期待データと実際の結果をまず キープロパティ で突き合わせます。突き合わせられたデータのペアはそれぞれ 値の比較 や NULLの比較 に従って、プロパティごとに比較されます。突き合わせに失敗したレコードがある場合、 全体の比較条件 に従って比較を行います。

キープロパティ

Excelでテスト条件を記述する場合、突き合わせに利用するキープロパティには2列目(B)で 検査キー [Key] を選んだものが利用されます。

キープロパティを複数指定した場合、それらは複合キーとして取り扱われます。つまり、プロパティ a と b をどちらも検査キーとして指定した場合、 a と b のいずれも同じ値であるレコードどうしで比較を行います。

値の比較

突き合わせられた期待データと結果のレコードは、 値の比較 で指定された方法でプロパティごと比較されます。ただし、ここで「検査キー」が指定されたプロパティについては、 キープロパティ として取り扱われます。

これは、以下のような比較方法を選択できます。

検査対象外 [-]

常に成功。

完全一致 [=]

プロパティの値が完全に同じ場合のみ成功。

部分一致 [<=]

期待データで指定した文字列が、結果データに含まれている場合のみ成功。文字列のみ。

現在日付 [Today]

結果データの日付または時刻が、テスト開始時日から終了日の間に収まっている場合のみ成功。期待データに指定した値は無視される。日付または時刻のみ。

現在時刻 [Now]

結果データの日付または時刻が、テスト開始時時刻から終了時刻の間に収まっている場合のみ成功。期待データに指定した値は無視される。日付または時刻のみ。

特殊ルール [Expr]

特定用途向けの特殊なルールを利用します。指定可能なルールは後述の オプション 参照してください。

全てのプロパティに対して上記の方法を元に比較を行い、すべて成功したらそのレコードに対する値の比較が成功したことになります。

Hint

現在日付や現在時刻が必要になるのは、テスト対象のプログラム内で「現在のシステム日付」や「現在のシステム時刻」を利用した場合などが考えられます。テストプログラムの実行中に日付が変更されてしまった場合などでも、これらの比較は正しく動作します。

NULLの比較

値の比較とは別に、プロパティごとにNULLとの比較を行います。

これは、以下のような比較方法を選択できます。

通常比較 [-]

特別な比較を行わない。

NULLなら常に成功 [AA]

結果データのプロパティがNULLなら、 値の比較 の比較に関係なく成功

NULLなら常に失敗 [DA]

結果データのプロパティがNULLなら、 値の比較 の比較に関係なく失敗

NULLでなければ常に成功 [AP]

結果データのプロパティがNULLでなければ、 値の比較 の比較に関係なく成功

NULLでなければ常に失敗 [DP]

結果データのプロパティがNULLでなければ、 値の比較 の比較に関係なく失敗

Hint

ここで「通常比較」を指定し、結果データの値がNULLであった場合、 値の比較 で指定した方法によって取り扱いが多少異なります。

値の比較で「完全一致」を選んでいた場合、期待データもNULLである場合のみ成功します。完全一致以外では、常に失敗します。

オプション

New in version EVR-2.0.0: Format バージョン EVR-2.0.0 以降

値の比較 に 特殊ルール [Expr] を指定した場合、オプション列に以下のルールを定義することができます。

誤差範囲の指定

値の比較の際に、期待値に対する実際値の誤差を許容する範囲を指定することができます。

誤差範囲の指定方法は以下の通りです。

特殊ルールオプション: 誤差範囲の指定

ルール指定

ルールの意味

指定の例

~数値

実際値は期待値に対して指定した数値の上下範囲内である

~10

~+数値

実際値は期待値に対して指定した数値の上範囲内である

~+20

~-数値

実際値は期待値に対して指定した数値の下範囲内である

~-30

誤差範囲の単位は、比較対象のプロパティ型が数値型の場合はその数値、 DATE 型の場合は日数、 DATETIME の場合は秒となります。

大小関係の指定

値の比較の際に、期待値に対する実際値の大小関係を指定することができます。

大小関係の指定方法は以下の通りです。

特殊ルールオプション: 大小関係の指定

ルール指定

ルールの意味

>

実際値は期待値より大きい

<

実際値は期待値より小さい

>=

実際値は期待値以上である

<=

実際値は期待値以下である

全体の比較条件

シートの2行目では、全体の比較条件を指定できます。具体的な動作は下記の通りです。

全体の比較方法

比較方法

期待データがない場合

実際の結果がない場合

全てのデータを検査 [Strict]

比較失敗

比較失敗

余計なデータを無視 [Expect]

比較失敗

無視

存在しないデータを無視 [Actual]

無視

比較失敗

お互い存在するデータのみ検査 [Intersect]

無視

無視

なお、全体の比較条件に 比較しない [-] を選択した場合、レコードを一切比較しません。つまりこの場合、 値の比較 や NULLの比較 等は無視されます。

テストデータの利用

作成したテストデータのExcelファイルは、テストドライバーの規約に従って配置して下さい。このファイルをテストドライバーから参照する際には、次のような形式で指定します。

<ファイルパス>#<シート名>

指定の名前のシートを利用する。

<ファイルパス>#:<シート番号>

指定の位置のシートを利用する。シート番号は左から順に 1, 2, …

Attention

Eclipseのワークスペース上のファイルをExcelで操作している場合、Excelで保存したファイルがEclipseに反映されない場合があります。その場合、該当ファイルをパッケージエクスプローラー等から選択し、コンテキストメニューから Refresh などを選択してください。

コマンドラインインターフェース

テストデータテンプレートの生成 で説明した方法のほかに、 com.asakusafw.testdata.generator.excel.Main [https://docs.asakusafw.com/0.10.3/release/api/com/asakusafw/testdata/generator/excel/Main.html] を実行してテストデータテンプレートを生成することもできます。

指定できるオプションは次の通りです。

-format

出力するテンプレートの形式。種類については formatオプション を参照。

-source

対象のデータモデルを定義したDMDLスクリプトへのパス一覧。スクリプトファイル化、それを含むディレクトリを指定する。パス区切り文字で区切って複数指定可能。

-output

生成したテストデータテンプレートを出力する先のディレクトリ。存在しない場合には自動生成する。

-encoding (optional)

DMDLスクリプトのエンコーディング。未指定の場合はプラットフォーム依存。

-plugin (optional)

DMDLコンパイラのプラグインファイル。パス区切り文字で区切って複数指定可能。

formatオプション

-format オプションには次の値を指定できます。

ALL

入力データ、期待データ、テスト条件を記述できるシートを生成 (Excel 97形式)。

DATA

入力データまたは期待データを記述できるシートのみを生成 (Excel 97形式)。

RULE

テスト条件を記述できるシートのみを生成 (Excel 97形式)。

INOUT

入力データと期待データを記述できるシートを生成 (Excel 97形式)。

INSPECT

期待データとテスト条件を記述できるシートを生成 (Excel 97形式)。

ALLX

入力データ、期待データ、テスト条件を記述できるシートを生成 (Excel 2007形式)。

New in version 0.5.3.

DATAX

入力データまたは期待データを記述できるシートのみを生成 (Excel 2007形式)。

New in version 0.5.3.

RULEX

テスト条件を記述できるシートのみを生成 (Excel 2007形式)。

New in version 0.5.3.

INOUTX

入力データと期待データを記述できるシートを生成 (Excel 2007形式)。

New in version 0.5.3.

INSPECTX

期待データとテスト条件を記述できるシートを生成 (Excel 2007形式)。

New in version 0.5.3.

Attention

Excel 97形式のシートではカラム数が256までという制限があるため、256より多いプロパティを持つデータモデルに対して入力データシートと出力データシートですべてのプロパティを扱うことができないという制約があります。

ビルド設定ファイル

build.gradle に コマンドラインインターフェース で説明したオプションを指定することができます。

以下例のように、generateTestbook タスクに対して GenerateTestbookTask 3 が提供するプロパティの値を設定します。

generateTestbook.outputSheetFormat = 'ALLX'

3

com.asakusafw.gradle.tasks.GenerateTestbookTask [https://docs.asakusafw.com/0.10.3/release/gradle-plugins/com/asakusafw/gradle/tasks/GenerateTestbookTask.html]

JSONによるテストデータ定義

この文書では、JSONでテストデータを定義する方法について紹介します。

入力データと期待データ

JSON形式でテストデータを定義するには、 .json という拡張子のUTF-8テキストファイルを作成して下さい。ここにJSON形式の「オブジェクト」を列挙することで、それらを入力データや期待データの列として利用できます。

{
    "sid": 1,
    "shipped_date": "2010-12-01 12:00:00",
    "item_code": 1
}
{
    "sid": 2,
    "shipped_date": "2010-12-01 12:00:00",
    "item_code": 2
}
{
    "sid": 3,
    "shipped_date": "2010-12-01 12:02:00",
    "item_code": 2
}

また、それぞれのプロパティ名はDMDLと同様に snake_case の形式で指定します。それぞれのプロパティに対し、以降で紹介する値を設定できます。

Attention

作成したJSONファイルは、必ず .json という拡張子で保存して下さい。それ以外の拡張子を指定した場合、テストドライバーはJSONファイルとして取り扱いません。

Attention

JSONファイルはJSONの配列ではなく、JSONのオブジェクトを列挙した形で指定してください。オブジェクトの区切りにカンマ等も不要です。

数値

数値を表す値を入力するには、プロパティにその数値を記述するか、またはその数値を表す文字列を記述します。

文字列が入力された場合、次の方法で適切な数値に変換します。

数値の変換方法

データ型

変換方法

long までの整数

Long.parseLong

double までの浮動小数点

Double.parseDouble

上記以外の数値

new BigDecimal(...)

その後、実際の型に合わせて値が切り詰められます。値が切り詰められる際に、オーバーフローやアンダーフローが発生する場合もあります。

Hint

精度の高い数値を利用したい場合、文字列の形式で指定しておく方が無難です。

文字列

文字列を入力するには、プロパティに文字列リテラルを指定します。

論理値

論理値を表す値を入力するには、 true または false を直接指定します。

日付と時刻

日付や時刻を表す値を入力するには、それぞれを表す文字列を記述します。現在のところ、日付は - (ハイフン) 区切りで時刻は : (コロン)区切り、日付と時刻はホワイトスペースで区切ります。

日付を指定する場合には、年月日のすべてを指定する必要があります ( "1999-12-31" など)。時刻を指定する場合には、24時間表記で時分秒を全て指定する必要があります ( "12:34:05" など)。

NULL値

プロパティにNULLを指定する場合、JSONオブジェクトからそのプロパティを取り除きます。テストドライバーは未定義のプロパティを単にNULLとして取り扱います。

テスト条件

現在のところ、JSONでテスト条件を記述することはできません。他の形式のテストデータと組み合わせて利用するか、テスト条件のみをJavaで直接記述して下さい。

テストデータの利用

作成したテストデータのJSONファイルは、テストドライバーの規約に従って配置して下さい。このファイルをテストドライバーから参照する際には、ファイルパスを直接指定します。

テストドライバー開発者ガイド

この文書では、テストドライバーの拡張方法について紹介します。

Todo

Application Testing > Developer Guide

データの直接入出力 - Direct I/O

Direct I/OはHadoopクラスターからバッチの入出力データを直接読み書きするための機構です。

主に以下のような特徴があります。

高速な入出力

Hadoopクラスターから直接データを分散して読み書きするため、WindGateなどの外部システム連携ツールを利用した場合に比べて高速な入出力を行えます。また、入力及び出力データの分割をサポートし、Hadoopクラスターと連携した効率的な入出力が可能です。

柔軟なデータソースの設定

バッチアプリケーションの開発と、運用時に利用するデータソースや入出力位置の指定を分離して行えます。また、データソースや入出力位置は複数を組み合わせて利用可能です。

柔軟な入出力ファイルパスの指定

入力パスにはバッチ引数やワイルドカード、サブディレクトリ検索などを指定できます。出力パスにはバッチ引数のほかデータの内容などを指定でき、ファイルの内容も特定のプロパティでソートできます。

様々なファイル形式に対応

CSVやカラムナフォーマットファイルなどのファイル形式とデータモデルとのマッピングに対応しています。 Asakusa Frameworkの外部で作成されたシーケンスファイルを利用することも可能です。

関連するドキュメント

Direct I/O スタートガイド

Direct I/O ユーザーガイド

Direct I/O CSV

Direct I/O TSV

Direct I/O formatted text

Direct I/O JSON

Direct I/O line

Direct I/O sequence file

Direct I/O Hive

Direct I/O コマンドラインツールユーザーガイド

Direct I/O CLI ユーザーガイド

Direct I/O スタートガイド

この文書では、Direct I/Oの簡単な利用方法について紹介します。

See also

Direct I/Oの詳しい利用方法については Direct I/O ユーザーガイド を参照してください。

アプリケーションの開発準備

アプリケーションの開発環境の構築手順や利用方法については、 Asakusa Framework スタートガイド を参照してください。この文書では開発環境の構築が完了しているものとして説明を行います。

データソースの設定

Direct I/Oの機構を利用するには、入出力の仲介を行う「データソース」の設定が必要です。主に以下のような設定を行います。

データソースの実装

データソースを配置する論理パス

データソースが実際に利用するファイルシステム上のパス

これらの設定は、 $ASAKUSA_HOME で指定したディレクトリ以下の core/conf/asakusa-resources.xml (以下「設定ファイル」)内に、Hadoopの設定ファイルと同様の形式でそれぞれ記述していきます。

データソースのマッピング

$ASAKUSA_HOME/core/conf/asakusa-resources.xml にはデフォルトの設定ファイルが作成されています。これは以下のような内容になっています。

asakusa-resources.xml

<?xml version="1.0" encoding="UTF-8"?>
<?xml-stylesheet type="text/xsl" href="configuration.xsl"?>
<configuration>
<!--
Default Implementations (for Development)
-->
    <property>
        <name>com.asakusafw.runtime.core.Report.Delegate</name>
        <value>com.asakusafw.runtime.core.Report$Default</value>
    </property>

    <property>
        <name>com.asakusafw.directio.root</name>
        <value>com.asakusafw.runtime.directio.hadoop.HadoopDataSource</value>
    </property>
    <property>
        <name>com.asakusafw.directio.root.path</name>
        <value>/</value>
    </property>
    <property>
        <name>com.asakusafw.directio.root.fs.path</name>
        <value>target/testing/directio</value>
    </property>
</configuration>

このうち、Direct I/Oに関係する項目 1 は以下のとおりです。

com.asakusafw.directio.root

データソースのJavaでの実装クラス名です。

Direct I/Oでは、それぞれのデータソースを識別するための識別子を com.asakusafw.directio.<DSID> の形式で指定します。デフォルトの設定では root というIDのデータソースが設定されていることになります。

Hadoopのファイルシステムを利用するには com.asakusafw.runtime.directio.hadoop.HadoopDataSource と指定します。

com.asakusafw.directio.root.path

このデータソースを配置する「論理パス」を表します。

論理パスは、 com.asakusafw.directio.<DSID>.path の形式で指定します。 DSLからはこの論理パスでデータソースを指定します。

論理パスはUnixのディレクトリのような構造を取り、 alpha/beta/gamma のように名前をスラッシュ ( / ) で区切って指定します。

特別な論理パスとして、ルートパスは / 一文字で指定します。

Tip

デフォルトの設定ではデータソース識別子 root にルートパスを表す論理パス / が割り当てられていますが、データソース識別子 root は特別な値ではなく、任意の値に変更することが出来ます。

com.asakusafw.directio.root.fs.path

データソースが実際に利用するファイルシステム上のパス「ファイルシステムパス」を表します。

ファイルシステムパスは、 com.asakusafw.directio.<DSID>.fs.path の形式で指定します。 Direct I/Oを利用したアプリケーションは、ここに指定されたファイルシステムパス以下のファイルを利用します。

ファイルシステムパスには target/testing/directio のように相対パスを使用したり、 hdfs://localhost:8020/user/asakusa のように完全URIを使用することができます。

相対パスを指定した場合、Hadoopのデフォルトファイルシステムのワーキングディレクトリからの相対パスが利用されます。

Hint

Hadoopのデフォルトファイルシステムとは、Hadoopの設定ファイル core-site.xml 内の fs.defaultFS (fs.default.name) に指定したファイルシステムです。また、デフォルトのワーキングディレクトリは、多くのHadoopディストリビューションではアプリケーション実行ユーザーのホームディレクトリです。

See also

ファイルシステムパスの形式について、詳しくは Direct I/O ユーザーガイド - ファイルシステムパスの形式 を参照してください。

Warning

ファイルシステムパス以下はテストドライバー実行時に削除されます。特にスタンドアロンモードのHadoopを利用時にデフォルトの設定のような相対パスを指定した場合、ホームディレクトリを起点としたパスと解釈されるため注意が必要です。

例えばホームディレクトリが /home/asakusa であった場合でデフォルト設定の相対パスを利用する場合、テスト実行の都度 /home/asakusa/target/testing/directio ディレクトリ以下が削除されることになります。

1

Direct I/Oに無関係の項目は、 実行時プラグイン の設定です。

サンプルアプリケーションの実行

Asakusa Framework スタートガイド と同様の手順でサンプルアプリケーションの実行を行いますが、ここでは Direct I/Oの機能説明を加えつつサンプルアプリケーションの実行手順を説明します。

データソースの設定

サンプルアプリケーションは、DSLから以下の論理パスを利用しています。

サンプルアプリケーションが利用するパス

論理パス

概要

master

マスタデータを配置するパス

sales

売上データを配置するパス

result

計算結果を出力するパス

上記の論理パスに対応するデータソースをそれぞれ配置するか、またはデフォルト設定のようにルート ( / ) に対してデータソースを配置してください。

以降の説明ではデータソースの設定には データソースのマッピング で説明したデフォルト設定をそのまま利用します。この場合、データソースはルートパス / を使用し、この論理パスに対応するファイルシステムパスは target/testing/directio が使用されます。

サンプルアプリケーションのビルド

データソースの設定が完了したら、サンプルアプリケーションのビルドを行います。

Warning

先述した通り、ビルド時に実行されるテストの実行中に、設定したデータソースのファイルシステムパスの内容がクリアされます。対応付けたファイルシステムパスをもう一度確認し、重要なデータがないようにしてください。

コマンドラインコンソールでアプリケーションプロジェクトのディレクトリに移動し、以下のコマンドを実行してください。

cd ~/workspace/example-app
./gradlew build

サンプルデータの配置

サンプルアプリケーションプロジェクトには src/test/example-dataset 以下にサンプルの入力ファイルが配置されています。これは以下のような構成になっています。

サンプルアプリケーションが利用するパス

サンプルデータの位置

対応する論理パス

src/test/example-dataset/master

master

src/test/example-dataset/sales

sales

hadoop fs -put コマンドを利用して、設定したファイルシステムパス上にサンプルデータを配置してください。以下はデフォルト設定を利用した場合のコマンド例です。

# スタンドアロンモードに対応するため、ホームディレクトリに移動しておく
cd ~
# ファイルシステムパス上のデータをクリアしておく
hadoop fs -rm -r target/testing/directio/*
# サンプルデータを配置する
hadoop fs -put <サンプルアプリケーションプロジェクトのパス>/src/test/example-dataset/master target/testing/directio/master
hadoop fs -put <サンプルアプリケーションプロジェクトのパス>/src/test/example-dataset/sales target/testing/directio/sales

Attention

直前に サンプルアプリケーションのビルド を実行している場合、ファイルシステムパス上にはテスト時に利用したデータが残っていることがあるため、データを配置する際には上の例のように、ファイルシステムパス上のデータをクリアしてから配置してください。

アプリケーションの実行

アプリケーション実行の手順は Asakusa Framework スタートガイド と同様です。

ここではローカルでアプリケーションを実行するためのコマンド例のみを示します。詳しくは Asakusa Framework スタートガイド の サンプルアプリケーションのデプロイ や サンプルアプリケーションの実行 を参考にしてください。

cd <サンプルアプリケーションプロジェクトのパス>
cp build/*batchapps*.jar $ASAKUSA_HOME/batchapps
cd $ASAKUSA_HOME/batchapps
jar xf *batchapps*.jar

$ASAKUSA_HOME/yaess/bin/yaess-batch.sh example.summarizeSales -A date=2011-04-01

アプリケーション実行結果の確認

Direct I/Oでは論理パスに配置したデータソース内のファイルやディレクトリ一覧をリストアップするコマンド $ASAKUSA_HOME/directio/bin/list-file.sh を提供しています。このコマンドを利用して、サンプルアプリケーションの出力結果を確認します。

list-file.sh は 第一引数にリストアップの対象とするベースパス、第二引数にベースパスからの相対パスや ファイル名のパターン を指定します。ここでは、論理パス result 配下のすべてのファイルをサブディレクトリ含めてリストするようコマンドを実行してみます。

$ASAKUSA_HOME/directio/bin/list-file.sh result "**/*"

上記のコマンドを実行した場合、サンプルデータでは以下のような結果が表示されます。

Starting List Direct I/O Files:
...
file:/home/asakusa/target/testing/directio/result/category
file:/home/asakusa/target/testing/directio/result/error
file:/home/asakusa/target/testing/directio/result/category/result.csv
file:/home/asakusa/target/testing/directio/result/error/2011-04-01.csv

デフォルト設定の場合、論理パス result に対応するデータソースはルートパス / に対応するデータソース root が使用されます。また、データソース root に対応するファイルシステムパスは相対パス target/testing/directio が使用されます。

上記はスタンドアロンモード上のHadoop対して実行しているため、Hadoopのワーキングディレクトリであるユーザーのホームディレクトリ ( 上記の例では /home/asakusa )配下の相対パスに結果が出力されています。

hadoop fs -text コマンドを利用して list-file.sh が出力したファイルシステムパスのファイル内容を確認します。

hadoop fs -text file:/home/asakusa/target/testing/directio/result/category/result.csv

上記のコマンドを実行した場合、サンプルデータでは以下のような結果が表示されます。

category/result.csv

カテゴリコード,販売数量,売上合計
1600,28,5400
1300,12,1596
1401,15,1470

このように、売上合計の降順で整列されたCSVになっています。

Attention

Direct I/Oの出力は論理パス result 上に行われます。つまり、出力データの実体は 論理パス result に配置したデータソースが実際に利用するファイルシステム上に出力されます。

Direct I/Oのデフォルト設定では、データソースが実際に利用するファイルシステムはHadoopファイルシステムです。 Hadoopでは設定により、Hadoopファイルシステムの実体が変わることに注意してください。例えば、Hadoopがスタンドアロンモードの場合は、Hadoopファイルシステムはローカルファイルを使用し、Hadoopが分散モードの場合はHDFSを使用するといったケースが多いでしょう。

つまり開発環境でHadoopをスタンドアロンモードで使用する場合は通常Direct I/Oの出力はローカルファイルシステム上に出力されますが、WindGate/CSVと異なり設定次第ではローカルファイルシステム以外にも出力されることがあることに注意してください。

アプリケーションの開発

以降ではアプリケーションの開発における、Direct I/O特有の部分について紹介します。

データモデルクラスの生成

Direct I/OではモデルをDMDLで記述します。 DMDLの記述方法については「 DMDLスタートガイド 」などを参考にしてください。

DMDLスクリプトはプロジェクトの src/main/dmdl ディレクトリ以下に配置し、スクリプトのファイル名には .dmdl の拡張子を付けて保存します。

データモデルクラスを作成するには、データモデルの定義情報を記述後にGradleの compileDMDL タスクを実行します。

./gradlew compileDMDL

CSV入出力への対応

データモデルの定義情報を作成したら、CSVの入出力に対応させたいデータモデルに対して、 @directio.csv という属性を指定します。この属性が指定されたデータモデルは、宣言されたプロパティと同じ順序のフィールドを持つCSVファイルの入出力に対応します。

この属性は、データモデルの宣言の直前に指定します。以下は記述例です。

@directio.csv
example_model = {
    // ... プロパティの定義
};

この状態でデータモデルを作成すると、データモデルのほかに以下の3つのクラスが作成されます。

<パッケージ名>.csv.<データモデル名>CsvFormat

<パッケージ名>.csv.Abstract<データモデル名>CsvInputDescription

<パッケージ名>.csv.Abstract<データモデル名>CsvOutputDescription

See also

CSV入出力に関するより細かな設定については Direct I/O CSV を参照してください。

Asakusa DSLの記述

Direct I/Oを利用する場合でも、Asakusa DSLの基本的な記述方法は同様です。 Direct I/O特有の部分は、以下に示す ファイルシステム上のCSVファイルを入力に利用する と ファイルシステム上にCSVファイルを出力する 部分のみです。

それ以外の部分については、 Asakusa DSLスタートガイド を参照してください。

ファイルシステム上のCSVファイルを入力に利用する

開発環境のCSVファイルをインポートしてHadoopの処理を行う場合、 CSV入出力への対応 で生成した <パッケージ名>.csv.Abstract<データモデル名>CsvInputDescription クラスのサブクラスを作成して必要な情報を記述します。

このクラスでは、下記のメソッドをオーバーライドします。

String getBasePath()

入力に利用する論理パスを戻り値に指定します。

論理パスについては データソースのマッピング を参照してください。

String getResourcePattern()

入力に利用するファイル名のパターンを戻り値に指定します。 getBasePath() で指定したパスを起点に、このパターンの名前を持つファイルを検索します。

パターンには * (ワイルドカード) や {alpha|beta|gamma} (選択)などを利用できます。パターンの完全なドキュメントについては Direct I/O ユーザーガイド を参照してください。

以下は Document というデータモデルを宣言した場合の実装例です。

public class DocumentFromCsv extends AbstractDocumentCsvInputDescription {

    @Override
    public String getBasePath() {
        return "input";
    }

    @Override
    public String getResourcePattern() {
        return "documents-*.csv";
    }
}

ここで記述した内容は、ジョブフローの入力に対して、 @Import を利用して指定します。

ファイルシステム上にCSVファイルを出力する

ジョブフローの処理結果をCSVファイルにエクスポートする場合、 CSV入出力への対応 で生成した <パッケージ名>.csv.Abstract<データモデル名>CsvOutputDescription クラスのサブクラスを作成して必要な情報を記述します。

このクラスでは、下記のメソッドをオーバーライドします。

String getBasePath()

出力に利用する論理パスを戻り値に指定します。

論理パスについては データソースのマッピング を参照してください。

String getResourcePattern()

出力先のファイル名のパターンを戻り値に指定します。 getBasePath() で指定したパスを起点に、このパターンの名前でファイルを作成します。

パターンには {property_name} (プレースホルダ) や [0..100] (ランダムな値 2 ) などを利用できます。ここに指定したプロパティの文字列表現がファイル名に埋め込まれます。プロパティ名はDMDLのプロパティ名と同様、すべて小文字で単語をアンダースコア ( _ ) で区切ってください。

See also

パターンの完全なドキュメントについては Direct I/O ユーザーガイド を参照してください。

List<String> getOrder()

それぞれの出力ファイルの内容をソートするプロパティを指定します。

それぞれのプロパティは +property_name で昇順、 -property_name で降順を表します。プロパティ名はDMDLのプロパティ名と同様、すべて小文字で単語をアンダースコア ( _ ) で区切ってください。

以下は Document というデータモデルを宣言した場合の実装例です。このデータモデルにはそれぞれ、カテゴリ名を表す category と、作成日付を表す date というプロパティがあるものとします。

public class DocumentToCsv extends AbstractDocumentCsvOutputDescription {

    @Override
    public String getBasePath() {
        return "output";
    }

    @Override
    public String getResourcePattern() {
        return "documents-{category}.csv";
    }

    @Override
    public List<String> getOrder() {
        return Arrays.asList("+date");
    }
}

上記の例では、論理パス output 以下に documents-<カテゴリ名>.csv というファイルをカテゴリごとに作成し、内容を作成日付の昇順でソートします。

ここで記述した内容は、ジョブフローの入力に対して、 @Export を利用して指定します。

Attention

出力するデータが存在しない場合、ファイルは一つも作成されません。これは、ファイル名にプレースホルダを指定していない場合でも同様です。

2

「ランダムな値」を指定した場合、レコードごとにランダムな番号を生成して宛先のファイルを振り分けます。レコード数が少ない場合、ランダムな番号が偏ってしまって、範囲にあるすべてのファイルが生成されるとは限りません。

Direct I/O ユーザーガイド

この文書では、Direct I/Oの利用方法について紹介します。

データソース

Direct I/Oはファイルシステム上に配置したジョブフローの入出力データを、実行エンジンから直接読み書きするための機構です。ここでのファイルシステムにはHadoop File System APIを経由しますので、ローカルファイルシステムだけでなくHDFSなどのHadoopから参照可能なファイルを利用できます。

Direct I/Oでは、読み書きする対象のことを「データソース」として抽象化しています。それぞれのデータソースはいずれかの「論理パス」上に配置します。このパスは唯一のルートを持つツリー状の構造で、ルートを含む任意のノードに対してデータソースを配置できます。これらの配置設定はAsakusa Framework側の設定ファイル上で行います。

DSLではデータソースそのものを指定せずに、入出力を行う先の論理パスのみを指定します。ジョブフローの実行時には論理パスからデータソースを引き当て、そのデータソースに対する入出力が行われます。

入力のアーキテクチャ

Direct I/Oの入力には次のような特徴があります。

大きなデータを分割して読みだす

以降では上記の特徴に関するアーキテクチャを紹介します。

入力データの分割

Direct I/Oでデータを読み出す際、以下の条件をすべて満たした場合にデータを小さな断片に分割し、並列に読み出すことが可能です。

データソースが分割をサポートしている

データの形式が分割をサポートしている

データが十分に大きい

データを分割できない場合にも、ファイルごとに並列に読み出すことは可能です。

出力のアーキテクチャ

Direct I/Oの出力には次のような特徴があります。

出力ファイルを内容によって分割したりソートしたりできる

Direct I/O全体の出力を簡易的なトランザクションで行う

以降では上記の特徴に関するアーキテクチャを紹介します。

出力ファイルの分割と内容のソート

Direct I/Oでファイルを出力する際、出力内容を元にファイルの分割と内容のソートを行うことができます。

Direct I/Oの出力では、出力先のファイルごとに並列にファイルを作成します。このとき、単一の出力先に対して並列に書き出すことはできないため、出力ファイルが1つである場合や、ファイルの大きさに極端な偏りが見られる場合には全体の性能が低下します。

Direct I/Oでは出力ファイル名の生成パターンを指定して出力ファイルを分割する、もしくは出力ファイル名の生成パターンを細かく指定せず、実行エンジン側で一意な名前を決めるワイルドカードを使用することで高速化が望めます。

Hint

ワイルドカードを指定した場合はソートが使えなくなるなど、出力ファイルの指定にはいくつかのトレードオフが存在します。詳細は後述の 出力ファイル名のパターン を参照してください。

簡易的な出力のトランザクション

Direct I/Oで複数のデータソースに対して出力を行う際、内部では簡易的なトランザクション処理を行っています。これにより、いずれかのデータソースに出力する際にエラーとなってしまった場合でも、最終的な出力先のデータを全く破壊しないか、または整合性のとれた出力結果を得られるようになっています。

Direct I/Oのトランザクション処理は主に以下の流れで行います。

システムディレクトリ 1 に「トランザクション情報ファイル」を作成する

出力ファイルごとに「試行領域 (attempt area)」にファイルを作成する

すべてのファイルを試行領域へ作成したら、それぞれのデータをデータソースの「ステージング領域 (staging area)」に移動する

失敗した場合は試行領域のデータをクリアする

すべての出力についてステージング領域へのファイル移動が成功した場合、システムディレクトリに「コミットマークファイル」をアトミックに作成する

いずれかが失敗した場合はコミットマークファイルを作成しない

で作成したコミットマークファイルが存在する場合、それぞれのステージング領域の内容を最終的な出力先に移動し、コミットマークファイルを削除する

コミットマークファイルが存在しない場合は、ステージング領域の内容をクリアする

トランザクション情報ファイルを削除する

Attention

データを最終的な出力先に移動する際に、標準的なデータソースではすでに移動先にデータが存在する場合に上書きします。

なお、試行領域はタスク試行ごとに、ステージング領域はデータソースごとにそれぞれ作成されます。

上記の仕組み上、Direct I/Oによる出力には次のような制約があります。

試行領域 > ステージング領域 > 最終的な出力先 とデータを移動させるため、データの移動に時間がかかるデータソースでは速度が出ない 2

コミットマークファイル作成から削除までの間、データソースは一時的に整合性が失われる

コミットマークファイル作成から削除までの間に処理が失敗した場合、トランザクションの修復が行われるまで整合性が失われる

Warning

バージョン 0.10.3 ではトランザクションの修復を自動的には行いません。トランザクションのメンテナンス を参考に、手動で修復を行ってください。

コミットマークファイル自体が障害によって失われた場合、データソースの整合性が失われる

同一の出力先に対して複数のジョブフローから出力を行った場合、結果が不安定になる (競合に対するロック等は行わない)

1

詳しくは システムディレクトリの設定 を参照してください。

2

例えばHadoopファイルシステムを経由して Amazon Simple Storage Service ( Amazon S3 [http://aws.amazon.com/s3/] )を利用する場合、データの移動に時間がかかるようです。後述の Amazon S3での設定例 も参考にしてください。

データソースの設定

Direct I/Oの機構を利用するには、入出力の仲介を行う「データソース」の設定が必要です。主に以下のような設定を行います。

データソースの実装

データソースを配置する論理パス

データソースが実際に利用するファイルシステム上のパス

これらの設定は、 $ASAKUSA_HOME で指定したディレクトリ以下の core/conf/asakusa-resources.xml (以下「設定ファイル」)内に、以下の形式でそれぞれ記述していきます。

asakusa-resources.xml

<property>
    <name>プロパティ名</name>
    <value>値</value>
</property>

Attention

このファイルはAsakusa FrameworkがHadoopのジョブを実行する際に利用する共通の設定ファイル 3 です。 Hadoop本体の core-site.xml 等と同様の形式 4 ですが、 ${...} 形式でのシステムプロパティの展開をサポートしていません。

3

実行時プラグイン の設定にも利用しています。

4

http://hadoop.apache.org/docs/r1.2.1/api/org/apache/hadoop/conf/Configuration.html

データソースの追加

データソースを追加するには設定ファイルに次の項目を追加します。

データソースを追加する際の設定

名前

値

com.asakusafw.directio.<DSID>

データソースの実装クラス名

com.asakusafw.directio.<DSID>.path

データソースを配置する論理パス

設定の名前に含まれる <DSID> はそれぞれのデータソースを表す識別子です。 <DSID> には半角アルファベットの大文字小文字、半角数字、半角アンダースコア ( _ ) の組み合わせを指定できます。複数のデータソースを利用する場合にはデータソースごとに識別子を変えて指定してください。

データソースの実装は、現在のところ Hadoopのファイルシステムを利用したデータソース のみを提供しています。詳しくは対象の項を参照してください。

論理パスとはDirect I/Oのそれぞれのデータソースを配置する仮想的なパスで、DSLからこのパスを指定してデータソースを利用します。このパスは alpha/beta/gamma のように名前をスラッシュ ( / ) で区切って書きます。

特別なパスとして、ルートパスは / 一文字で指定します。

論理パスの解決

DSLで指定した論理パスから実行時にデータソースを引き当てる際、次のような方法でデータソースの検索が行われます。

論理パスに対してデータソースが配置されている場合、そのデータソースを利用する

論理パスに対してデータソースが配置されていない場合、現在の論理パスの親パスに対して再帰的にデータソースの検索を行う

ただし、現在の論理パスがルートである場合、データソースの検索は失敗する

つまり、DSLで指定した論理パスに対して、親方向に最も近いデータソースを検索して利用しています。

また、データソースを配置した論理パスよりもDSLで指定した論理パスの方が長い (つまり、サブパスが指定された) 場合、データソースを配置した論理パスからの相対パスをファイルパスの先頭に利用します。

たとえば、データソースを a/b に配置し、DSLでは論理パスに a/b/c/d と指定した場合、データソースからの相対パスは c/d となります。さらにDSLでファイルパスに e/f と指定すると、結果のファイルパスは c/d/e/f となります。

Note

この論理パスの機構は、Unixのファイルシステムのマウントを参考に設計しています。

Hadoopのファイルシステムを利用したデータソース

データソースの実装として、HadoopのファイルシステムAPI ( FileSystem 5 ) を利用したものを提供しています。

本データソースを利用する場合、実装クラス名 ( com.asakusafw.directio.<DSID> ) には com.asakusafw.runtime.directio.hadoop.HadoopDataSource を指定します。また、利用するファイルシステムについては、Hadoopの本体側であらかじめ設定を行っておく必要があります。

Direct I/Oの設定ファイルには、対象のデータソースに対してさらに論理パスに対するファイルシステム上のパスを表す「ファイルシステムパス」の設定が必要です。

Hadoopのファイルシステムを利用したデータソース

名前

形式

値

com.asakusafw.directio.<DSID>.fs.path

URI

ファイルシステム上のパス

5

org.apache.hadoop.fs.FileSystem

ファイルシステムパスの形式

ファイルシステムパスには次の3種類の形式を指定できます。

相対パス

Hadoopのデフォルトファイルシステム 6 のワーキングディレクトリ 7 からの相対パスを利用します。

なお、デフォルトファイルシステムにローカルファイルシステムを指定している場合、ワーキングディレクトリは必ずユーザーのホームディレクトリになります。

絶対パス

Hadoopのデフォルトファイルシステム上の絶対パスを利用します。

たとえば /var/log や /tmp/directio などです。

完全URI

URIに対応するファイルシステム、ホスト、パスを利用します。

たとえば file:///home/asakusa や hdfs://localhost:8020/user/asakusa などです。

6

Hadoopの設定ファイル core-site.xml 内の fs.defaultFS (fs.default.name) に指定したファイルシステムです。

7

多くのHadoopディストリビューションでは、デフォルトのワーキングディレクトリはアプリケーション実行ユーザーのホームディレクトリです。

Warning

ファイルシステムパス以下はテストドライバー実行時に全て削除されます。特にスタンドアロンモードのHadoopを利用時に相対パスを指定した場合、ホームディレクトリを起点としたパスと解釈されるため注意が必要です。

Hint

ファイルシステムパスの形式は環境や構成に応じて使い分けるべきです。

例えば開発環境ではOSやHadoopの設定に依存しない相対パスの設定が便利でしょう。運用環境ではワーキングディレクトリに依存しない絶対パスの設定が安定するかもしれません。

また、複数種類のデータソースを使用し、Hadoopのデフォルトファイルシステム以外のファイルシステムを利用する場合は完全URIを使用する必要がありますが、この場合すべてのファイルシステムパスを完全URIで記述したほうが可読性が向上するかもしれません。

絶対パスや完全URIはHadoop側の設定を変更した場合に、その設定に追従する必要があるかもしれないので注意が必要です。

論理パスとファイルシステムパスの対応付け

Hadoopのファイルシステムを利用したデータソースでは、指定したファイルシステム上のパス ( com.asakusafw.directio.<DSID>.fs.path ) を起点に論理パスとファイルを対応付けます。具体的には、次のような手順で対応付けます。

DSLで指定した論理パスとファイル名から、 論理パスの解決 にある方法で実際のファイルパスを計算する

計算したファイルパスを、指定したファイルシステム上のパスからの相対パスとみなす

たとえば、データソースを hadoop に配置し、DSLでは論理パスに hadoop/asakusa , ファイル名に data.csv と指定した場合、実際に利用するファイルパスは asakusa/data.csv となります。さらに起点となるファイルシステム上のパスが hdfs://localhost/user であった場合、対応付けられる最終的なファイルシステム上のパスは hdfs://localhost/user/asakusa/data.csv となります。

ファイルの分割読み出しの設定

Hadoopのファイルシステムを利用したデータソース において、 入力データの分割 は次のように設定します。いずれのプロパティも必須ではありません。

ファイルの分割読み出しに関する設定

名前

形式

値

com.asakusafw.directio.<DSID>.fragment.min

long

断片の最小バイト数

com.asakusafw.directio.<DSID>.fragment.pref

long

断片の推奨バイト数

...fragment.min に0未満の値を指定した場合、入力データの分割は行われません。未指定の場合は 16MB 程度に設定されます。

...fragment.pref が未指定の場合、 64MB程度に設定されます。また、 ...fragment.min 未満の値は設定できません。

分割の最小バイト数や推奨バイト数は、次のようにデータの形式で上書きされることがあります。

データの形式が入力データの分割を許可しない場合、ファイルは分割されない

データの形式で指定した最小バイト数がデータソースで指定したものより大きな場合、データの形式で指定したものを優先する

データの形式で推奨バイト数が指定されている場合、データの形式で指定したものを優先する

推奨バイト数が最小バイト数未満になる場合、推奨バイト数は最小バイト数の値を利用する

入力データの分割を許可している場合、このデータソースにおいてそれぞれの断片は次の制約をすべて満たします。

それぞれの断片は最小バイト数未満にならない

それぞれの断片は推奨バイト数の2倍以上にならない

Hint

Hadoop本体に指定したスプリットの設定はここでは使用しません。通常の場合は既定の設定値で問題なく動作するはずですが、ファイルの途中からデータを読み出すような操作に多大なコストがかかるようなファイルシステムにおいては、ファイルの分割を行わないなどの設定が必要になります。

トランザクションの設定

Hadoopのファイルシステムを利用したデータソース において、 簡易的な出力のトランザクション は次のように設定します。いずれのプロパティも必須ではありません。

トランザクションに関する設定

名前

形式

値

com.asakusafw.directio.<DSID>.fs.tempdir

URI

トランザクション用に利用するファイルシステム上のパス

com.asakusafw.directio.<DSID>.output.staging

boolean

ステージング領域を利用するかどうか

com.asakusafw.directio.<DSID>.output.streaming

boolean

試行領域に直接出力するかどうか

com.asakusafw.directio.<DSID>.threads.commit

int

ステージング領域から最終的な出力先にデータを移動させる処理に使用するスレッド数

...fs.tempdir を省略した場合、このパスは com.asakusafw.directio.<DSID>.fs.path 下の _directio_temp というディレクトリになります。明示的に設定を行う場合、この値は ...fs.path と同一のファイルシステムでなければなりません 8 。

トランザクションが修復不可能な状態になった場合や、処理中に実行エンジンが異常終了した場合、 ...fs.tempdir 以下に処理の途中結果が残されている場合があります。

...output.staging を省略した場合、この値は true (ステージング領域を利用する) となります。ステージング領域を利用しない場合、試行領域から最終的な出力先へ結果のデータを直接移動します。

...output.streaming を省略した場合、この値は true (試行領域に直接出力する) となります。試行領域に直接出力しない場合、ローカルテンポラリ領域にファイルを作成したのち、ファイルの作成が成功した際にステージング領域にファイルを移動します。この時利用するローカルテンポラリ領域は ローカルテンポラリ領域の設定 があらかじめ必要です 9 。

...threads.commit を省略した場合、この値は 1 （シングルスレッドで処理する）となります。出力ファイル数が多い場合や、ファイルの移動に時間がかかるデータソースの実装を利用する場合、この値を増やすことでトランザクション処理にかかる時間を短縮できる可能性があります。なお ...output.staging が false の場合、この設定は無効です。

8

具体的には、 ...fs.tempdir 以下のファイルを ...fs.path 以下のディレクトリに FileSystem.rename() で移動できる必要があります。

9

試行領域に直接出力をしない場合にローカルテンポラリ領域が設定されていないと実行時にエラーとなります。

Keep Aliveの設定

Hadoopの一部のファイルシステム実装では、データを大きなブロックで転送するような実装になっています。大きなブロックを転送する際にアプリケーションの応答がなくなり、実行エンジンによってはタイムアウトとなって処理が強制終了されてしまいます。

Hadoopのファイルシステムを利用したデータソース において、Keep Aliveの設定を行うことで上記の問題を回避できます。

Keep Aliveの設定

名前

形式

値

com.asakusafw.directio.<DSID>.keepalive.interval

long

ハートビート信号を送る間隔 (ミリ秒)

...keepalive.interval を省略した場合、Direct I/OでのKeep Aliveの設定は無効になります。

Attention

Keep Aliveの設定は注意深く行ってください。アプリケーションがフリーズしてしまうなど、ファイルの転送とは別の原因で応答がなくなっても、本機能のせいで正常にタイムアウト処理が行われなくなる可能性があります。

データソースの設定例

ここではいくつかのデータソースの設定例を示します。

HDFSでの設定例

以下はHDFSの入出力を行う場合の設定例です。

asakusa-resources.xml

<property>
    <name>com.asakusafw.directio.hdfs</name>
    <value>com.asakusafw.runtime.directio.hadoop.HadoopDataSource</value>
</property>
<property>
    <name>com.asakusafw.directio.hdfs.path</name>
    <value>hdfs/var</value>
</property>
<property>
    <name>com.asakusafw.directio.hdfs.fs.path</name>
    <value>hdfs://localhost:8020/var/asakusa</value>
</property>

HDFSは直接の出力やファイルの移動を低コストで行えるようになっています。そのため、特別な設定を行わなくてもそれなりに動作します。

Amazon S3での設定例

Amazon Simple Storage Service ( Amazon S3 [http://aws.amazon.com/s3/] )の入出力を行う場合の設定例です。

asakusa-resources.xml

<property>
    <name>com.asakusafw.directio.s3</name>
    <value>com.asakusafw.runtime.directio.hadoop.HadoopDataSource</value>
</property>
<property>
    <name>com.asakusafw.directio.s3.path</name>
    <value>s3/spool</value>
</property>
<property>
    <name>com.asakusafw.directio.s3.fs.path</name>
    <value>s3://example/var/spool</value>
</property>
<property>
    <name>com.asakusafw.directio.s3.output.staging</name>
    <value>false</value>
</property>
<property>
    <name>com.asakusafw.output.system.dir</name>
    <value>s3://example/var/system</value>
</property>

本ドキュメントの作成時点では、Hadoopのファイルシステムを経由してS3を利用する場合、出力ファイルの移動にコストがかかるようです。このため、上記の設定では次のようなことを行っています。

ステージ領域をスキップする ( ...output.staging = false )

ステージ領域を利用する場合、タスクが全て成功した後にファイルの名前変更を行います。S3上でのファイル名変更はHDFS上のそれより時間がかかります。

Attention

上記の例はステージ領域をスキップするよう設定していますが、この設定によりトランザクション処理が行えなくなる点に注意してください。

複数のデータソースを利用する設定例

複数のデータソースを組み合わせて利用する場合、設定ファイルのデータソース( com.asakusafw.directio.<DSID> ) のうち、 <DSID> の部分を別々のものに設定します。

asakusa-resources.xml

<property>
    <name>com.asakusafw.directio.data</name>
    <value>com.asakusafw.runtime.directio.hadoop.HadoopDataSource</value>
</property>
<property>
    <name>com.asakusafw.directio.data.path</name>
    <value>data</value>
</property>
<property>
    <name>com.asakusafw.directio.data.fs.path</name>
    <value>hdfs://localhost:8020/user/directio/var</value>
</property>
<property>
    <name>com.asakusafw.directio.master</name>
    <value>com.asakusafw.runtime.directio.hadoop.HadoopDataSource</value>
</property>
<property>
    <name>com.asakusafw.directio.master.path</name>
    <value>data/master</value>
</property>
<property>
    <name>com.asakusafw.directio.master.fs.path</name>
    <value>hdfs://localhost:8020/user/directio/master</value>
</property>

上記の例は論理パス data と data/master に対してそれぞれ data , master というDSIDのデータソースを指定する例です。論理パスとファイルシステムパスをそれぞれ次のように対応づけています。

論理パスとファイルシステムパスの対応付け

ID

論理パス

ファイルシステムパス

data

data

hdfs://localhost:8020/user/directio/var

master

data/master

hdfs://localhost:8020/user/directio/master

上記の設定では、DSLから data というパスが指定された場合に data というデータソースを利用し、 data/master というパスが指定された場合に master というデータソースを利用します。

それ以外に、 data/transaction や data/2012 など、 data 以下でなおかつ data/master と無関係なパスが指定された場合にも data というデータソースを利用します。 master というデータソースも同様に、 data/master/item など、 data/master のサブパスを指定した場合にも利用されます。

DSLで論理パスより長いパスを指定した場合、論理パスにマッチした残りの部分はそのままファイルシステム上のパスに利用します。上記の設定でDSLから data/2012/01 と指定した場合、実行時には hdfs://localhost:8020/user/directio/var/2012/01 というパスとして処理が行われます。

なお、 data とは関係ないパス（たとえば var/log など）が指定された場合には、対応するデータソースが見つからないためエラーとなります。これを避けるにはデフォルト設定のように、ルートパス ( / ) に対してデータソースを配置します。

Hint

データソースの識別子(<DSID>)は実行時のログメッセージにも利用されるため、わかりやすいものにしてください。

その他の設定

データソースの設定以外に、Direct I/Oの全体を通した設定を行えます。

システムディレクトリの設定

システムディレクトリはDirect I/Oの管理情報を保持するためのディレクトリで、以下の形式で設定します。この内容はHadoop本体の設定ファイルに書いても、Direct I/Oの設定ファイルに書いてもどちらでも有効です 10 。

システムディレクトリの設定

名前

形式

値

com.asakusafw.output.system.dir

URI

Hadoopファイルシステム上のシステムディレクトリ

システムディレクトリの設定が省略された場合、Hadoopが利用するデフォルトファイルシステム上の、 <ワーキングディレクトリ>/_directio を利用します。またプロパティの値の中に、Javaのシステムプロパティを ${システムプロパティ名} という形式で利用できます。

Hint

システムディレクトリはトランザクションの管理情報など、Direct I/Oを利用するうえで重要な情報が記録されます。そのため、信頼性の高いデータストア上か、Direct I/Oを利用するうえで重要性の高いデータストアと同じ領域内に配置することを推奨します。

10

正確に言えば、データソースの設定もHadoop本体の設定ファイル内に記載できます。ただし、データソースの設定はDirect I/O独自の設定ファイルに記載することを推奨します。

ローカルテンポラリ領域の設定

ローカルテンポラリ領域は、Direct I/Oの処理を実際に行っているコンピューターのローカルファイルシステム上のディレクトリです。トランザクションの設定 において、「ステージング領域を利用しない」という設定を行った際に、出力ファイルを一時的に作成します。

この内容は以下の形式で設定します。なお、Hadoop本体の設定ファイルに書いても、Direct I/Oの設定ファイルに書いてもどちらでも有効です。

ローカルテンポラリ領域の設定

名前

形式

値

com.asakusafw.output.local.tempdir

ファイルパス

ローカルファイルシステム上のテンポラリディレクトリ

ローカルテンポラリ領域はローカルファイルシステム上の絶対パスを指定します。この設定が省略された場合、ローカルテンポラリ領域は利用できなくなります。

設定に対するディレクトリが存在しない場合、ローカルテンポラリ領域の利用時に自動的にディレクトリを作成します。

ログの設定

Direct I/Oに関するログは実行エンジンのログの設定を利用して行います。それぞれの実行エンジンに関連するドキュメントを参照してください。

ファイルの入出力

Direct I/Oを利用してファイルを入出力するには、 Hadoopのファイルシステムを利用したデータソース などの設定をしておきます。

また、データモデルと対象のファイル形式をマッピングする DataFormat 11 の作成が必要です。 DataFormat のサブタイプとして、任意のストリームを取り扱う BinaryStreamFormat 12 や、Hadoopのファイルを取り扱う HadoopFileFormat 13 を現在利用できます( DataFormat は直接実装できません ) 。

なお、以降の機能を利用するには次のライブラリやプラグインが必要です。

Direct I/Oで利用するライブラリ等

ライブラリ

概要

asakusa-directio-vocabulary

DSL用のクラス群

asakusa-directio-plugin

DSLコンパイラプラグイン

asakusa-directio-test-moderator

テストドライバープラグイン

asakusa-directio-dmdl

DMDLコンパイラプラグイン

Hint

Asakusa Gradle Plugin ユーザーガイド の手順に従ってプロジェクトテンプレートから作成したプロジェクトは、これらのライブラリやプラグインがGradle Pluginによってデフォルトで利用可能になっています。

11

com.asakusafw.runtime.directio.DataFormat [https://docs.asakusafw.com/0.10.3/release/api/com/asakusafw/runtime/directio/DataFormat.html]

12

com.asakusafw.runtime.directio.BinaryStreamFormat [https://docs.asakusafw.com/0.10.3/release/api/com/asakusafw/runtime/directio/BinaryStreamFormat.html]

13

com.asakusafw.runtime.directio.hadoop.HadoopFileFormat [https://docs.asakusafw.com/0.10.3/release/api/com/asakusafw/runtime/directio/hadoop/HadoopFileFormat.html]

データフォーマットの作成

Direct I/Oはいくつかのファイルフォーマットにおいて、 DataFormat の実装クラスをDMDLコンパイラの拡張を利用して自動的に生成する機能を提供したり、実装用の基底クラスを提供しています。

Direct I/Oが提供する各ファイルフォーマットの利用方法については、以下のドキュメントを参照してください。

Direct I/O CSV (CSV形式のテキストファイルの入出力)

Direct I/O formatted text (区切り文字によってレコードやフィールドが構成される汎用的なテキストファイルの入出力)

Direct I/O JSON (JSON形式のファイルの入出力)

Direct I/O line (任意の行文字列の入出力)

Direct I/O sequence file (Hadoopシーケンスファイルの利用)

Direct I/O Hive (カラムナフォーマットファイルの利用)

また、各ファイルフォーマットの定義から DataFormat の実装クラスを生成する方法については、 Direct I/O スタートガイド - データモデルクラスの生成 などを参照してください。

ファイルを入力に利用するDSL

Direct I/Oを利用してファイルからデータを読み出す場合、 DirectFileInputDescription 14 クラスのサブクラスを作成して必要な情報を記述します。

このクラスでは、下記のメソッドをオーバーライドします。

String getBasePath()

入力に利用する論理パスを戻り値に指定します。

ここには ${変数名} の形式で、バッチ起動時の引数やあらかじめ宣言された変数を利用できます。利用可能な変数はコンテキストAPIで参照できるものと同様です。

String getResourcePattern()

入力に利用するファイル名のパターンを戻り値に指定します。 getBasePath() で指定したパスを起点に、このパターンの名前を持つファイルを検索します。

形式については 入力ファイル名のパターン を参照してください。

Class<?> getModelType()

処理対象とするデータモデルオブジェクトの型を表すクラスを戻り値に指定します。

このメソッドは、自動生成される骨格ではすでに宣言されています。

Class<? extends DataFormat<?>> getFormat()

DataFormat の実装クラスを戻り値に指定します。

このメソッドは、自動生成される骨格ではすでに宣言されています。

Class<? extends DataFilter<?>> getFilter()

DataFilter 15 のサブクラスを戻り値に指定します。

詳細については 入力データのフィルター を参照してください。

boolean isOptional()

入力にとるファイルが存在しない場合に、バッチ全体を異常終了させるには false を、空の入力として処理を続行する場合には true を、それぞれ戻り値に指定します。

省略した場合、ファイルが存在しない場合にバッチ全体を異常終了させます ( false )。

DataSize getDataSize()

入力の推定データサイズを返します。

省略した場合、データサイズは不明 ( DataSize.UNKNOWN ) となります。

以下は実装例です。

public class DocumentFromFile extends DirectFileInputDescription {

    @Override
    public String getBasePath() {
        return "example";
    }

    @Override
    public String getResourcePattern() {
        return "**/data-*.csv";
    }

    @Override
    public Class<?> getModelType() {
        return Document.class;
    }

    @Override
    public Class<? extends DataFormat<?>> getFormat() {
        return DocumentCsvFormat.class;
    }

    @Override
    public Class<? extends DataFilter<?>> getFilter() {
        return DocumentFilter.class;
    }

    @Override
    public boolean isOptional() {
        return true;
    }

    @Override
    public DataSize getDataSize() {
        return DataSize.LARGE;
    }
}

14

com.asakusafw.vocabulary.directio.DirectFileInputDescription [https://docs.asakusafw.com/0.10.3/release/api/com/asakusafw/vocabulary/directio/DirectFileInputDescription.html]

15

com.asakusafw.runtime.directio.DataFilter [https://docs.asakusafw.com/0.10.3/release/api/com/asakusafw/runtime/directio/DataFilter.html]

入力ファイルのベースパス

getBasePath() に指定した論理パスは「ベースパス」と呼ばれます。

実行時にはこのベースパスのみを利用して入力元のデータソースを探します。そのため、以下の2つでは異なる結果になる場合があります。

basePath = "data/asakusa" , resourcePattern = "file.csv"

basePath = "data" , resourcePattern = "asakusa/file.csv"

上記の場合、 data/asakusa という論理パスにデータソースが配置されている場合、それぞれが参照するデータソースは異なるものになります。この規則について詳しくは、 論理パスの解決 を参照してください。

また、ベースパスには ${変数名} の形式でバッチ引数を利用できます。

ベースパスには * を使ったワイルドカード指定はできません。また、 |, [, ], {, } といった文字は利用できません。

入力ファイル名のパターン

getResourcePattern() にはファイル名だけでなくワイルドカードなどのパターン用の文字列も利用できます。

ここに利用できるパターンは以下の通りです。

利用できるパターン

文字列

名前

概要

名前文字

リテラル

そのままファイル名として利用します。対象のデータソースが利用できるファイル名のうち、 / , \ , $ , * , ? , # , | , { , } , [ , ] 以外の文字を利用できます。

/

名前区切り

パスに含まれる名前の区切り文字です。

${バッチ引数名}

変数

実行時にバッチ引数と置き換えます。対象のバッチ引数は、変数を含まない任意のパターンの組み合わせである必要があります。

*

ワイルドカード

0個以上の任意の名前文字とマッチします。

{..|..|..}

選択

| で区切られたいずれかの名前にマッチします。 .. の部分には名前文字と名前区切りの組み合わせのみを指定できます。

上記のほかに、特別なディレクトリやファイル名として ** を利用できます。これは、検索対象以下のすべてのサブディレクトリ(自身のディレクトリも含む)とそれに含まれるファイルにマッチします。

ただし、 ** はディレクトリやファイル名の一部としては利用できません。たとえば、 **.csv というパターンは利用できず、代わりに **/*.csv と書きます。

Hint

「変数」に関する挙動は、パターンの解釈の前に一度変数をすべて展開し、展開後の文字列をパターンとして解釈して利用しています。

入力データのフィルター

getFilter() で入力フィルタークラスを指定すると、Direct I/O を利用してファイルからデータを読み出す際に、ファイル単位やレコード単位で読み出すデータを制限できます。

Experimental

Asakusa Framework バージョン 0.10.3 では、Direct I/O の入力フィルターは試験的機能として提供しています。

この入力フィルタークラスは、 DataFilter 16 を継承したクラスを、アプリケーションの入力データに合わせて個別に実装する必要があります。 DataFilter を継承し、下記のメソッドを必要に応じてオーバーライドしてください。

void initialize(Context context)

入力フィルターを初期化する際にフレームワークから呼び出されます。

context からバッチ引数を取得できます。入力フィルターの中では Framework API を利用できませんので、バッチ引数が必要な場合はここで取得する必要があります。

boolean acceptsPath(String path)

入力データのうち、ファイルを丸ごとフィルターする際に利用します。このメソッドが true を返す場合には対象のファイルを入力として利用し、 false を返す場合には対象のファイルを入力から除外します。

path には、入力データのフルパスが格納されています。ベースパスやファイル名のパターンとは異なる可能性がある点に注意が必要です。

boolean acceptsData(T data)

入力データのうち、個々のレコードをフィルターする際に利用します。このメソッドが true を返す場合には対象のレコードを入力として利用し、 false を返す場合には対象のレコードを入力から除外します。

入力フィルターを利用する際には、以下の点に注意してください。

入力フィルター内でフレームワークAPIを利用できない

入力フィルタークラスの各メソッド内では、フレームワークAPIを利用できませんとくにバッチ引数などを利用する際には、 initialize() メソッドの Context オブジェクトから取得してください

テストドライバーからの実行で入力フィルターを利用できない

テストドライバーから入力フィルターを含むジョブフローやバッチをテストする場合、入力フィルターは自動的に無効化されますテストデータを用意する際には「フィルター適用後」のデータを指定し、入力フィルターのテストは個別に行ってください

以下は入力フィルタークラスの実装例です。

public class RegexInputFilter extends DataFilter<Object> {

    private Pattern accept;

    @Override
    public void initialize(Context context) {
        // バッチ引数から正規表現パターンを取り出す
        String s = context.getBatchArguments().get("pattern");
        accept = Pattern.compile(s);
    }

    @Override
    public boolean acceptsPath(String path) {
        // 正規表現パターンにマッチするファイルのみを入力に利用
        return accept.matcher(path).matches();
    }
}

16

com.asakusafw.runtime.directio.DataFilter [https://docs.asakusafw.com/0.10.3/release/api/com/asakusafw/runtime/directio/DataFilter.html]

ファイルを出力に利用するDSL

Direct I/Oを利用してデータをファイルに書き出す場合、 DirectFileOutputDescription 17 クラスのサブクラスを作成して必要な情報を記述します。

このクラスでは、下記のメソッドをオーバーライドします。

String getBasePath()

出力に利用する論理パスを戻り値に指定します。

ここには ${変数名} の形式で、バッチ起動時の引数やあらかじめ宣言された変数を利用できます。利用可能な変数はコンテキストAPIで参照できるものと同様です。

String getResourcePattern()

出力に利用するファイル名のパターンを戻り値に指定します。 getBasePath() で指定したパスを起点に、このパターンが表すパスにそれぞれのファイルを出力します。

パターンには {property_name:format} (プレースホルダ) などを利用できます。これは指定したプロパティの内容を、指定のフォーマットでファイル名に埋め込みます。

詳しくは 出力ファイル名のパターン を参照してください。

List<String> getOrder()

それぞれの出力ファイルの内容をソートするプロパティを指定します。

それぞれのプロパティは +property_name で昇順、 -property_name で降順を表します。プロパティ名はDMDLのプロパティ名と同様、すべて小文字で単語をアンダースコア ( _ ) で区切ってください。

省略した場合、出力ファイルのソートを行いません。

List<String> getDeletePatterns()

出力を行う前に削除するファイル名パターンの一覧を戻り値に指定します。 getBasePath() で指定したパスを起点に、これらのパターンが表すパスを消去した後に、ファイルの出力を行います。

パターンには * (ワイルドカード) など、 入力ファイル名のパターン と同様のものを利用できます。

省略した場合、ファイルの削除を行いません。

Class<?> getModelType()

処理対象とするデータモデルオブジェクトの型を表すクラスを戻り値に指定します。

このメソッドは、自動生成される骨格ではすでに宣言されています。

Class<? extends DataFormat<?>> getFormat()

DataFormat の実装クラスを戻り値に指定します。

このメソッドは、自動生成される骨格ではすでに宣言されています。

以下は実装例です。

public class DocumentToFile extends DirectFileOutputDescription {

    @Override
    public String getBasePath() {
        return "example";
    }

    @Override
    public String getResourcePattern() {
        return "{date:yyyy/MM}/data.csv";
    }

    @Override
    public List<String> getOrder() {
        return Arrays.asList("+id");
    }

    @Override
    public List<String> getDeletePatterns() {
        return Arrays.asList("${oldyear}/*/data.csv");
    }

    @Override
    public Class<?> getModelType() {
        return Document.class;
    }

    @Override
    public Class<? extends DataFormat<?>> getFormat() {
        return DocumentCsvFormat.class;
    }
}

Hint

出力先のファイルがすでに存在する場合、古いファイルを削除してからこの出力で上書きします。ただし、ファイルに対するレコードがひとつも存在しない場合にはファイル自体が作成されず、古いファイルが残ってしまう場合があります。

このため、出力先にワイルドカードやランダムな値を利用する場合には、 getDeletePatterns() を利用してファイルを削除しておいたほうが良い場合があります。

17

com.asakusafw.vocabulary.directio.DirectFileOutputDescription [https://docs.asakusafw.com/0.10.3/release/api/com/asakusafw/vocabulary/directio/DirectFileOutputDescription.html]

出力ファイルのベースパス

getBasePath() に指定した論理パスは「ベースパス」と呼ばれます。

実行時にはこのベースパスのみを利用して出力先のデータソースを探します。そのため、以下の2つでは異なる結果になる場合があります。

basePath = "data/asakusa" , resourcePattern = "file.csv"

basePath = "data" , resourcePattern = "asakusa/file.csv"

上記の場合、 data/asakusa という論理パスにデータソースが配置されている場合、それぞれが参照するデータソースは異なるものになります。この規則について詳しくは、 論理パスの解決 を参照してください。

また、ベースパスには ${変数名} の形式でバッチ引数を利用できます。

ベースパスには * を使ったワイルドカード指定はできません。また、 |, [, ], {, } といった文字は利用できません。

出力ファイルのベースパスは、次のような制約があります。

同一ジョブフローの入力が、ある出力のベースパスと同じまたはそのサブパスであってはならない

同一ジョブフローの出力が、ある出力のベースパスと同じまたはそのサブパスであってはならない

Note

上記の制約はトランザクションの制御やテストのために導入した制約です。出力に対してはこのような制約がありますが、2つの入力が同じベースパスを利用することは可能です。

出力ファイル名のパターン

getResourcePattern() にはファイル名だけでなくプロパティの内容からファイル名を計算するための、プレースホルダも利用できます。

ここに利用できるパターンは以下の通りです。

出力ファイル名に利用できるパターン

文字列

名前

概要

名前文字

リテラル

そのままファイル名として利用します。対象のデータソースが利用できるファイル名のうち、 / , \ , $ , * , ? , # , | , { , } , [ , ] 以外の文字を利用できます。

/

名前区切り

パスに含まれる名前の区切り文字です。

${バッチ引数名}

変数

実行時にバッチ引数と置き換えます。対象のバッチ引数は、名前文字または名前区切りの組み合わせである必要があります。

{property:format}

プレースホルダ

プロパティの内容を指定のフォーマットで文字列化して利用します。プロパティはDMDLと同様に snake_case の形式でプロパティ名を指定します。

[開始番号..終了番号]

ランダムな値

開始番号以上、終了番号以下のランダムな数値に置き換えます。それぞれの番号は0以上かつ2の31乗未満で、開始番号より終了番号のほうが大きな数値である必要があります。

*

ワイルドカード

分散環境上での出力に都合のよい任意の文字列を利用します。ただし、この出力にはプレースホルダとランダムな値、およびファイル内のソート機能 18 を利用できなくなります。

Attention

出力するレコード数が「ランダムな値」の範囲よりも十分に大きくない場合、ランダムな値のすべての範囲に対するファイルが生成されない場合があります。

Attention

出力ファイル名のパターンでは、変数の展開後の文字列にプレースホルダ、ランダムな値、ワイルドカードを表す文字列を含められません。この制約は将来緩和されるかもしれません。

Hint

出力ファイルが1つになってしまう場合や、出力ファイルのサイズに大きな偏りができてしまう場合、「ランダムな値」を利用することでパフォーマンスを向上させられる場合があります。

Hint

「ランダムな値」をゼロ埋めしたい場合、 [0..9][0..9] のように書けます。

Hint

「ワイルドカード」は制約が多い代わりに高速に動作する可能性があります。ワイルドカード文字を置換する際に、実行エンジンごとに異なる形式の文字列を利用します。

プレースホルダ ( {property:format} ) には次のようなフォーマットを利用できます。

プレースホルダに使用できるフォーマット

形式

データ型

概要

: とそれ以降を省略

すべて

toString() によって文字列化

:<日付>

DATE

: 以降を SimpleDateFormat.format() によって文字列化

:<日時>

DATETIME

: 以降を SimpleDateFormat.format() によって文字列化

:<数値書式>

BYTE, SHORT, INT, LONG, FLOAT, DOUBLE, DECIMAL

: 以降を DecimalFormat.format() によって文字列化

<日付> や <日時> には SimpleDateFormat 19 形式のパターンを指定します。たとえば、パターンに data/{date:yyyy/MM}.csv と指定すると、プロパティ date の内容を元に data/<年>/<月>.csv のようなファイルを年と月の情報からそれぞれ作成します。さらに内容をソートするプロパティにも date を指定すると、ファイルを年と月で分割した後に日にちでソートして出力できます。

<数値書式> には DecimalFormat 20 形式のパターンを指定します。

出力ファイル名については 出力ファイルの分割と内容のソート も参照してください。

Attention

出力するデータが存在しない場合、ファイルは一つも作成されません。これは、ファイル名にプレースホルダを指定していない場合でも同様です。

18

DirectFileOutputDescription.getOrder() ( ファイルを出力に利用するDSL を参照 )

19

java.text.SimpleDateFormat

20

java.text.DecimalFormat

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

Direct I/Oを利用したジョブフローやバッチのテストは、Asakusa Frameworkの通常のテスト方法で行えます。テスト方法については アプリケーションのテスト - TestDriver を参照してください。

ここでは、Direct I/Oを使ってテストドライバーを実行する際の動作や注意点を説明します。

テスト実行時の動作

以下はテスト実行時のテストドライバーの挙動です。

テスト実行時の設定

テストドライバーを使ったテスト実行時には、Direct I/Oの データソースの設定 は通常の実行環境と同様に、開発環境にインストールしたAsakusa Frameworkの設定ファイル $ASAKUSA_HOME/core/conf/asakusa-resources.xml が使用されます。必要に応じてこのファイルを編集し、適切な設定を行ってください。

入出力のクリア

テストドライバーの入出力が指定された場合、テストの実施前に入出力の対象がすべて削除されます。このとき、DSLの getBasePath() で指定した論理パス以下のすべての内容を削除します。

Warning

上記のような挙動のため、データソースの入出力対象はできるだけ制限するようにしてください。

入力データの作成

入力データの作成時、指定された入力ファイルのパターンに対して一つだけファイルを作成します。この時、下記のルールをもとに作成するファイルパスを計算します。

テスト時の入力ファイル名の変換ルール

文字列

名前

変換後

名前文字

リテラル

そのまま利用します

/

名前区切り

そのまま利用します

${バッチ引数名}

変数

テストに指定したバッチ引数で置き換えます

*

ワイルドカード

__testing__ という文字列に置き換えます

{..|..|..}

選択

最左の文字列をそのまま利用します

Note

この規則は暫定的なもので、将来変更されるかもしれません。

出力データの取得

出力された結果データの取得時、テストドライバーはDSLの getBasePath() で指定した論理パス以下のすべての内容を取得します。このため、バッチのテストで複数のジョブフローが同一のベースパスに出力を行う場合、正しく動作しません。

Note

この規則は暫定的なもので、将来変更されるかもしれません。

Attention

現在、ジョブフローの出力に対する初期データの作成 ( .prepare() ) はサポートしていません。

データフォーマットに対応したファイルをテストデータに指定

Direct I/Oを利用したアプリケーションのテストでは、Direct I/Oのデータフォーマットに対応するファイルをテストデータとして指定することも可能です。

例えば Direct I/O CSV を利用するアプリケーションでは、このフォーマット定義に対応するCSVファイルをテストの入力データや期待データとして指定することができます。

演算子のテスト

演算子のテストでは、DataLoader を利用して演算子の入力となるデータモデルオブジェクトをDirect I/Oのデータフォーマットに対応するファイルから生成することができます。

詳しくは、テストドライバーユーザーガイド - 演算子のテスト - DataLoader を参照してください。

データフローのテスト

データフローのテストでは、入力データと期待データをDirect I/Oのデータフォーマットに対応するファイルから生成することができます。

詳しくは、テストドライバーユーザーガイド - データフローのテストデータ作成 - Direct I/Oファイル形式 を参照してください。

入出力データのカウント情報

Direct I/Oはバッチアプリケーションの実行終了時に、入出力データのレコード件数やバイト数などの情報を集計してログに出力します。

以下、入出力データのカウント情報の出力例です。

...
Direct I/O file input: 3 entries
  itemInfo:
    number of input records: 9
    input file size in bytes: 1,017
  salesDetail:
    number of input records: 34
    input file size in bytes: 739
  storeInfo:
    number of input records: 5
    input file size in bytes: 275
  (TOTAL):
    number of input records: 48
    input file size in bytes: 2,031
Direct I/O file output: 2 entries
  categorySummary:
    number of output records: 3
    output file size in bytes: 1,326
  errorRecord:
    number of output records: 3
    output file size in bytes: 1,617
  (TOTAL):
    number of output records: 6
    output file size in bytes: 2,943

カウント情報に表示される項目は、アプリケーションで利用する実行エンジン毎に異なります。

Attention

Direct I/O Hive を利用した入出力データのカウント情報では、入力データファイルのバイト数 ( input file size in bytes ) は実際のファイルサイズとは多少異なる値が表示されます。

トランザクションのメンテナンス

Direct I/Oのファイル出力時には、 簡易的な出力のトランザクション を行っています。出力を開始する前にシステムディレクトリに対してトランザクションの情報を作成し、トランザクション処理の完了後にこれらの情報をクリアしています。

以降では、トランザクションが中断された際にこれらを手動で修復する方法について紹介します。なお、いずれのメンテナンス用コマンドについても、コマンドを起動した環境のHadoopのログ設定 21 を利用してログを出力します。

21

詳しくは ログの設定 を参照してください。

トランザクション情報の一覧を表示

残っているトランザクション情報の一覧を表示するには、 $ASAKUSA_HOME/directio/bin/list-transaction.sh コマンドを引数なしで実行します。このコマンドを実行すると、以下の情報を表示します。

表示されるトランザクションの情報

セクション

内容

Date

トランザクションを開始した日時

Execution ID

対象のジョブフローの実行ID

Status

トランザクションの状態

Comments

補助的な情報

上記のうち、 Status を調べることで対象のトランザクションの状態が分かります。特に重要な状態は Committed (コミット済み) で、この場合には最終的な出力先が不整合な状態になっている場合があります。

また、以降のコマンドでは Execution ID (実行ID) の情報を元にトランザクションの修復操作を行います。

コミットの適用

コミット済みのトランザクションを最終的な出力先に反映させるには、 $ASAKUSA_HOME/directio/bin/apply-transaction.sh コマンドを実行します。コマンドの引数にはトランザクションに対応する実行IDを指定してしてください。

このコマンドが対象とするトランザクション処理は、 Committed (コミット済み) でなければなりません。それ以外のトランザクション処理に対してこのコマンドを実行しても何も行いません。

このコマンドの実行が成功した場合、トランザクション情報の一覧にコマンドの対象が出現しなくなります。

このコマンドの実行に失敗した場合、出力先のデータソースに何らかの異常が発生している可能性があります。データソースを正常な状態に戻した後に再度コミットを適用するか、または トランザクションの破棄 を実行して出力に不整合があるままトランザクションを破棄できます。

Warning

コミットを適用する順序には注意が必要です。先に適用した出力は、後に適用した出力で上書きされてしまいます。

Note

このコマンドでは、ベストエフォートでのコミットの適用を行っています。複数のデータソースが存在し、そのうち一つが常にコミットの適用に失敗してしまう場合、即座に適用処理を停止せずにほかのデータソースに対してコミットを適用したのち、エラーとしています。

トランザクションの破棄

任意のトランザクション処理を破棄するには、 $ASAKUSA_HOME/directio/bin/abort-transaction.sh コマンドを実行します。コマンドの引数にはトランザクションに対応する実行IDを指定してしてください。

Warning

このコマンドはトランザクションのロールバックを行う のではなく 、単にトランザクションを破棄します。 Committed (コミット済み) のトランザクションに対してこの処理を実行すると、最終的な出力は不整合な状態になる場合があります。

このコマンドの実行が成功した場合、トランザクション情報の一覧にコマンドの対象が出現しなくなります。また、それぞれのデータソース上でステージング領域や試行領域の中間データを削除します。

Attention

ただし、ローカルテンポラリ領域 22 内の試行領域については削除されません。これらは別の手段で削除する必要があります。

このコマンドの実行に失敗した場合、出力先のデータソースに何らかの異常が発生している可能性があります。データソースを正常な状態に戻した後に再度実行するか、またはコマンド実行時のログを参考に、トランザクション情報自体を削除してください。

22

ローカルテンポラリ領域の設定 を参照してください。

Direct I/O CSV

この文書では、Direct I/OからCSVフォーマットのファイルをインポート/エクスポートする方法について説明します。

Note

Direct I/O で CSVフォーマットを取り扱う方法として、本書で説明する方法の他に Direct I/O formatted text を利用することもできます。それぞれの機能のおおまかな差異や使い分けの指針については Direct I/O formatted text - 他のデータフォーマット機能との関係 を参照してください。

CSV形式のDataFormatの作成

CSV形式 1 に対応した DataFormat の実装クラスを自動的に生成するには、対象のデータモデルに対応するDMDLスクリプトに @directio.csv を指定します。

@directio.csv
document = {
    "the name of this document"
    name : TEXT;

    "the content of this document"
    content : TEXT;
};

上記のように記述してデータモデルクラスを生成すると、 <出力先パッケージ>.csv.<データモデル名>CsvFormat というクラスが自動生成されます。このクラスは DataFormat を実装し、データモデル内のプロパティが順番に並んでいるCSVを取り扱えます。

また、 単純な ファイルを入力に利用するDSL と ファイルを出力に利用するDSL の骨格も自動生成します。前者は <出力先パッケージ>.csv.Abstract<データモデル名>CsvInputDescription 、後者は <出力先パッケージ>.csv.Abstract<データモデル名>CsvOutputDescription というクラス名で生成します。必要に応じて継承して利用してください。

Hint

この機能を利用するには、DMDLコンパイラのプラグインに asakusa-directio-dmdl を追加する必要がありますが、 Asakusa Gradle Plugin ユーザーガイド の手順に従ってプロジェクトテンプレートから作成したプロジェクトは、これらのライブラリやプラグインがGradle Pluginによってデフォルトで利用可能になっています。

Note

この機構は WindGate のものと将来統合されるかもしれません。

1

ここでのCSV形式は、 RFC 4180 [https://tools.ietf.org/html/rfc4180.html] で提唱されている形式を一部変更したものです。文字セットをASCIIの範囲外にも拡張したり、CRLF以外にもLFのみも改行と見なしたり、ダブルクウォート文字の取り扱いを緩くしたりなどの拡張を加えています。 CSV形式の注意点 も参照してください。

CSV形式の設定

@directio.csv 属性には、次のような要素を指定できます。

CSV形式の設定

要素

型

既定値

内容

charset

文字列

"UTF-8"

ファイルの文字エンコーディング

allow_linefeed

論理値

FALSE

TRUE で値内にLFを含められる。 FALSE で不許可

has_header

論理値

FALSE

TRUE でヘッダの利用を許可。 FALSE で不許可

force_header

論理値

FALSE

TRUE でヘッダの利用を許可し、ヘッダの形式チェックを行わない。 FALSE で不許可

true

文字列

"true"

BOOLEAN 型の TRUE 値の表現形式 2

false

文字列

"false"

BOOLEAN 型の FALSE 値の表現形式 3

date

文字列

"yyyy-MM-dd"

DATE 型の表現形式

datetime

文字列

"yyyy-MM-dd HH:mm:ss"

DATETIME 型の表現形式

compression

文字列

なし（非圧縮）

ファイルの圧縮形式

2

設定した文字列と完全一致する場合のみ TRUE 値となり、それ以外は FALSE 値になります。 BOOLEAN 型はデータ読み込み時に 自動トリム が行われないため、入力データにスペースなどが入っている場合でも FALSE となる点に注意してください。

3

データ出力時の文字列表現としてのみ使用されます。データ入力時の BOOLEAN 値の判定には使用されません。

なお、 date および datetime には SimpleDateFormat 4 の形式で日付や時刻を指定します。

また、 compression には、 "gzip" または CompressionCodec 5 のサブタイプのクラス名を指定します 6 。ここで指定した圧縮形式で対象のファイルが読み書きされるようになりますが、代わりに 入力データの分割 が行われなくなります。

Attention

デフォルトでは allow_linefeed には FALSE が設定されていて、文字列の内部などに改行文字 LF を含められないようになっています。この設定を TRUE にすることでLFを含められるようになりますが、代わりに 入力データの分割 が行われなくなります。詳しくは CSV形式の注意点 を参照してください。

以下はDMDLスクリプトの記述例です。

@directio.csv(
    charset = "ISO-2022-JP",
    allow_linefeed = TRUE,
    has_header = TRUE,
    true = "1",
    false = "0",
    date = "yyyy/MM/dd",
    datetime = "yyyy/MM/dd HH:mm:ss",
    compression = "gzip",
)
model = {
    ...
};

4

java.text.SimpleDateFormat

5

org.apache.hadoop.io.compress.CompressionCodec

6

org.apache.hadoop.io.compress.DefaultCodec などが標準で用意されています

CSVフィールドの設定

CSVのフィールドに関する設定は、DMDLスクリプトのデータモデルに含まれるそれぞれのプロパティに @directio.csv.field 属性を指定します。

@directio.csv.field 属性には、次のような要素を指定できます。

CSVフィールドの設定

要素

型

既定値

内容

name

文字列

プロパティ名

CSV形式の設定 でヘッダを有効にしている場合に使用するCSVのヘッダのフィールド名

quote

文字列

default

各フィールド値のクォートに関する動作の指定。default , needed , always のいずれかを指定

name 要素に指定するフィールド名は、入力データの読み込み時のヘッダの形式チェックやデータ出力時のヘッダ文字列として使用されます。

quote 要素に関する動作の指定は以下の通りです。

needed : フィールド値にクォート処理が必要な値が含まれている場合にクォート処理を行う

always : フィールド値の内容に関わらず、常にクォート処理を行う

default : needed を指定した場合と同じ動作を行う

以下はCSVフィールドの設定を付加したDMDLスクリプトの記述例です。

@directio.csv
document = {
    "the name of this document"
    @directio.csv.field(name = "題名" , quote = "always")
    name : TEXT;

    "the content of this document"
    @directio.csv.field(name = "内容" , quote = "needed")
    content : TEXT;
};

ファイル情報の取得

解析中のCSVファイルに関する属性を取得する場合、それぞれ以下の属性をプロパティに指定します。

ファイル情報の取得に関する属性

属性

型

内容

@directio.csv.file_name

TEXT

ファイル名

@directio.csv.line_number

INT , LONG

テキスト行番号 (1起算)

@directio.csv.record_number

INT , LONG

レコード番号 (1起算)

上記の属性が指定されたプロパティは、CSVのフィールドから除外されます。

Attention

@directio.csv.line_number または @directio.csv.record_number が指定された場合、 入力データの分割 が行われなくなります。詳しくは CSV形式の注意点 を参照してください。

Attention

これらの属性はCSVの解析時のみ有効です。 CSVを書き出す際には無視されます。

CSVから除外するプロパティ

特定のプロパティをCSVのフィールドとして取り扱いたくない場合、プロパティに @directio.csv.ignore を指定します。

自動トリム

入力データの読み込み時に、プロパティ型が TEXT および BOOLEAN 以外のプロパティについては、入力データに対してトリムが行われます。

CSV形式の注意点

自動生成でサポートするCSV形式を利用するうえで、いくつかの注意点があります。

改行文字は CRLF または LF のみ、CRのみです

ただしCRのみを利用している場合、入力データの分割が正しく行われません

CSVに空の文字列を書き出しても、読み出し時に null として取り扱われます

論理値は復元時に、値が true で指定した文字列の場合には true , 空の場合には null , それ以外の場合には false となります

ヘッダが一文字でも異なる場合、解析時にヘッダとして取り扱われません

1レコードが10MBを超える場合、正しく解析できません

以下のいずれかが指定された場合、 入力データの分割 は行われなくなります

@directio.csv( compression = ... )

@directio.csv( allow_linefeed = TRUE )

@directio.csv.line_number

@directio.csv.record_number

Direct I/O TSV

この文書では、Direct I/Oを使ってTSVフォーマットのファイルをインポート/エクスポートするための拡張機能の使い方について説明します。

Deprecated

Asakusa Framework バージョン 0.10.0 以降、 Direct I/O TSV は非推奨機能となりました。 TSV形式のデータフォーマットを扱うには Direct I/O formatted text を利用することを推奨します。

Mavenアーティファクト

Direct I/OのTSVファイル連携モジュールはAsakusa FrameworkのMavenリポジトリにグループID com.asakusafw.sandbox を持つMavenアーティファクトとして登録されています。

Direct I/OのTSVファイル連携で使用するMavenアーティファクト

グループID

アーティファクトID

com.asakusafw.sandbox

asakusa-directio-dmdl-ext

Note

Sandoxモジュールとして提供するDirect I/Oの各フォーマット拡張機能は同一のMavenアーティファクトで提供しています。

TSVファイル連携モジュールの利用方法

TSVファイル連携モジュールを使用する場合はアプリケーションプロジェクトの build.gradle の dependencies ブロック内に依存定義を追加します。

build.gradle

dependencies {
    compile group: 'com.asakusafw.sandbox', name: 'asakusa-directio-dmdl-ext', version: asakusafw.core.version
｝

データモデルクラスの生成

DMDLに対するTSVファイル用拡張属性の追加

TSVファイル連携を行うために、DMDLに対してTSVファイルを扱うことを示す拡張属性を追加します。

各モデルのDMDLスクリプトに対して、モデル名の記述行の前行に拡張属性 @directio.tsv を付与します。

以下にTSVファイルを扱う場合のDMDLスクリプトの例を示します。

"テーブルEX1"
...
@directio.tsv
ex1 = {
    "SID"
    sid : LONG;
    "VALUE"
    value : INT;
    "STRING"
    string : TEXT;
};

TSV形式の設定

@directio.tsv 属性には、次のような要素を指定できます。

TSV形式の設定

要素

型

既定値

内容

charset

文字列

"UTF-8"

ファイルの文字エンコーディング

allow_linefeed

論理値

FALSE

TRUE で値内にLFを含められる。 FALSE で不許可

has_header

論理値

FALSE

TRUE に設定すると、読み込み時に先頭行をスキップし、書き込み時にモデルの定義内容に応じたヘッダ行を生成する。

compression

文字列

なし（非圧縮）

ファイルの圧縮コーデック

compression には、 "gzip" または org.apache.hadoop.io.compress.CompressionCodec のサブタイプのクラス名を指定します 1 。ここで指定した圧縮形式で対象のファイルが読み書きされるようになりますが、代わりにファイルの分割読み出しが行われなくなります。

Attention

デフォルトでは allow_linefeed には FALSE が設定されていて、文字列の内部などに改行文字 LF を含められないようになっています。この設定を TRUE にすることでLFを含められるようになりますが、代わりに 入力データの分割 が行われなくなります。

以下はDMDLスクリプトの記述例です。

@directio.tsv(
    charset = "ISO-2022-jp",
    has_header = TRUE,
    compression = "gzip",
)
model = {
    ...
};

1

org.apache.hadoop.io.compress.DefaultCodec などが標準で用意されています

ヘッダの設定

TSV形式の設定 でヘッダを有効にしている場合、出力の一行目にプロパティ名が表示されます。ここで表示される内容を変更するには、それぞれのプロパティに @directio.tsv.field 属性を指定し、さらに name 要素でフィールド名を指定します。

以下はヘッダの内容の付加したDMDLスクリプトの記述例です。

@directio.tsv
document = {
    "the name of this document"
    @directio.tsv.field(name = "題名")
    name : TEXT;

    "the content of this document"
    @directio.tsv.field(name = "内容")
    content : TEXT;
};

Attention

ヘッダの内容に対する検証は行いません。 Asakusa Frameworkが標準で提供しているCSV形式のフォーマットではヘッダ行に対する検証を行ない、モデル定義に対してヘッダの内容が一文字でも異なる場合ヘッダ行として扱われませんが、TSV形式ではヘッダの設定を有効にした場合、常に先頭行に対してデータの読み込みをスキップします。

ファイル情報の取得

解析中のTSVファイルに関する属性を取得する場合、以下の属性をプロパティに指定します。

ファイル情報の取得に関する属性

属性

型

内容

@directio.tsv.file_name

TEXT

ファイル名

上記の属性が指定されたプロパティは、TSVのフィールドから除外されます。

Attention

Direct I/O のCSV連携で提供している、行番号・レコード番号の取得機能 ( @directio.csv.line_number , @directio.csv.record_number )はTSV連携では提供していません。

Attention

これらの属性はTSVの解析時のみ有効です。 TSVを書き出す際には無視されます。

TSVから除外するプロパティ

特定のプロパティをCSVのフィールドとして取り扱いたくない場合、プロパティに @directio.tsv.ignore を指定します。

データモデルクラス生成コマンド

データモデルクラスの生成は通常のDMDLで提供する方法と同様に、Gradleの compileDMDL タスクを実行して生成します。

./gradlew compileDMDL

Asakusa DSLの記述

Direct I/OのTSVファイル連携を使った場合のAsakusa DSLの記述については、基本的な流れはCSVファイル連携を使った場合と同様です。 Direct I/OのCSVファイルによる連携の基本的な流れについては、Direct I/O スタートガイド などを参照してください。

以下ではAsakusa DSLの記述に関して、Direct I/OのCSVファイル連携とTSVファイル連携で異なる部分についてのみ説明します。

ファイルシステム上のTSVファイルを入力に利用する

TSVファイルをインポートしてHadoopの処理を行う場合、 データモデルクラスの生成 で生成した <パッケージ名>.tsv.Abstract<データモデル名>TsvInputDescription クラスのサブクラスを作成して必要な情報を記述します。

ファイルシステム上にTSVファイルを出力する

ジョブフローの処理結果をTSVファイルにエクスポートする場合、 データモデルクラスの生成 で生成した <パッケージ名>.tsv.Abstract<データモデル名>TsvOutputDescription クラスのサブクラスを作成して必要な情報を記述します。

TSVファイルフォーマット仕様

Direct I/OのTSV連携機能で扱うTSVファイルのフォーマット仕様について説明します。

Warning

現時点では、本項のTSVファイルフォーマットは暫定仕様です。

TSVフォーマット概要

TSVファイルは、MySQLの SELECT ... INTO OUTFILE で、次の指定をした場合に生成されるファイルフォーマットと同一です 2 。

FIELDS TERMINATED BY '\t' ENCLOSED BY '' ESCAPED BY '\\'

LINES TERMINATED BY '\n' STARTING BY ''

2

MySQL 5.1のデフォルトフォーマットと同一です。

TSVフォーマット詳細

各フィールドをDMDLスクリプトの順番に記述します。

フィールドの区切り文字にはタブ文字を使用します。

レコードの区切り文字は改行(LF)を使用します。

CR+LF は使用できません。

エスケープ文字には「\」を使用します。

エスケープ文字そのもの、改行(LF)、タブ文字をデータとして扱う場合は「\」を前に付加してエスケープします。

引用文字は使用しません。

最終レコードにも(LF)が必要です。

NULL値は「\N」で表します。

空文字はフィールド区切り文字間に何も文字を入れないことで表現します。

指数表記は使用しません。

Booleanは0/1で表します。

0:false , 1:true

Date, Datetimeは以下の書式で表します。

Date: YYYY-MM-DD

Datetime: YYYY-MM-DD HH:MM:SS

TSVファイルのサンプル

DMDLスクリプトに対応するTSVファイルの例を以下に示します。

サンプル:DMDLスクリプト

"テーブルEX1"
...
@directio.tsv
ex1 = {
    "SID"
    sid : LONG;
    "VALUE"
    value : INT;
    "STRING"
    string : TEXT;
};

サンプル:TSVファイル

Attention

以下サンプルのドキュメント上の区切り文字はスペースになっていますが、実際のファイルはタブ文字を使用してください。

1   111     hoge1
2   222     fuga2
3   333     bar3
4   111     hoge4
5   222     fuga5
6   333     bar6
7   111     hoge7
8   222     fuga8
9   444     bar9

Direct I/O formatted text

この文書では、レコードやフィールドを区切り文字によって分割する様々なデータ形式を Direct I/O で取り扱うための機能「Direct I/O formatted text」について説明します。

概要

Direct I/O formatted text は、Direct I/Oで以下のようなデータ形式を持つテキストファイルを読み書きするための汎用的な機能を提供します。

レコード間が改行文字で区切られている

フィールド間が任意の1文字(タブやカンマなど)で区切られている

フィールドの位置（並び順）がフィールドの種類に対応する

特徴

Direct I/O formatted text は、以下のような特徴を持っています。

多様なデータ形式を扱うきめ細かな設定が可能

テキストファイルのエンコーディングやフィールド間の区切り文字をはじめ、フィールド値の整形形式やエスケープの動作設定、 NULL や空文字に対する取り扱いなど、様々なデータ形式に関する設定をレコード全体、及びフィールド単位にそれぞれ設定することができます。

従来、Direct I/Oでデータ取り込みを行うために事前にデータ整形処理が必要であったような場合においても、Direct I/O formatted textを利用することで直接そのようなデータを取り扱うことが可能になります。

不整合データに対する柔軟な動作設定が可能

データ形式の定義と実際のデータの内容に不整合があった場合に、エラーとして異常終了とする、警告を出力して処理を継続する、または単にスキップするなど様々な動作がレコード全体、及びフィールド単位にそれぞれ設定可能です。エラーや警告時にはエラー箇所と不整合の内容を示す詳細な情報が出力されます。

これらの機能によって想定外のデータに対して迅速に対応できるほか、外部システムやアプリケーションの仕様変更などに伴いアプリケーションとデータに不整合が発生するような場合でも、柔軟な運用、移行を可能にすることを支援します。

データフォーマットの作成

Direct I/O formatted text を利用したデータフォーマットを定義するには、対象のデータモデルに対応するDMDLスクリプトにDirect I/O formatted text用のデータモデル属性を指定します。

本バージョン時点で、Direct I/O formatted textは以下の2種類のデータモデル属性が利用できます。

@directio.text.tabular

@directio.text.csv

この2種類のデータモデル属性で取り扱うデータフォーマットはいずれも 概要 で示したようなテキストファイルを扱うものです。その動作や設定可能な項目などは多くの部分で共通していますが、異なる部分は主にフィールド中のメタ文字に対する扱いと、デフォルトの設定です。ここでのメタ文字とは、フィールド区切り文字などのファイルフォーマット自体に関わる文字のことです。

以下、それぞれのデータモデル属性が扱うデータフォーマットの概要と使い方を説明します。

@directio.text.tabular

@directio.text.tabular はフィールド中のメタ文字を「エスケープシーケンス」によって扱います。エスケープシーケンスは「エスケープ文字＋後続文字」という形式でフィールドデータとして表現します。エスケープ文字として使用する文字や、エスケープ時の動作などは @directio.text.tabular 属性の設定により細かく指定することが可能です。

デフォルトの設定はエスケープシーケンスは無効、フィールド間の区切り文字はHT(水平タブ)、といった設定を持ちます。

この形式に対応した DataFormat の実装クラスを自動的に生成するには、対象のデータモデルに対応するDMDLスクリプトに @directio.text.tabular を指定します。

@directio.text.tabular
document = {
    "the name of this document"
    name : TEXT;

    "the content of this document"
    content : TEXT;
};

上記のように記述してデータモデルクラスを生成すると、 <出力先パッケージ>.text.<データモデル名>TabularTextFormat というクラスが自動生成されます。このクラスは DataFormat を実装し、データモデル内のプロパティが区切り文字によって分離されて順番に並んでいるようなテキストファイルを取り扱えます。

また、 単純な ファイルを入力に利用するDSL と ファイルを出力に利用するDSL の骨格も自動生成します。前者は <出力先パッケージ>.text.Abstract<データモデル名>TabularTextInputDescription 、後者は <出力先パッケージ>.text.Abstract<データモデル名>TabularTextOutputDescription というクラス名で生成します。必要に応じて継承して利用してください。

@directio.text.csv

@directio.text.csv は RFC 4180 [https://tools.ietf.org/html/rfc4180.html] で提唱されているCSVの形式に基いて、フィールド中のメタ文字を「クウォート」によって扱います。クウォート処理の基本的な動作は、フィールドにメタ文字が含まれる場合にフィールド全体をクウォート文字で囲うことで取り扱うものです。クウォート文字として使用する文字や、クウォート方式などは @directio.text.csv 属性の設定により細かく指定することが可能です。

デフォルトの設定はクウォート文字に " (ダブルクウォート)、フィールド間の区切り文字は , (カンマ)、といった設定を持ちます。

この形式に対応した DataFormat の実装クラスを自動的に生成するには、対象のデータモデルに対応するDMDLスクリプトに @directio.text.csv を指定します。

@directio.text.csv
document = {
    "the name of this document"
    name : TEXT;

    "the content of this document"
    content : TEXT;
};

上記のように記述してデータモデルクラスを生成すると、 <出力先パッケージ>.text.<データモデル名>CsvTextFormat というクラスが自動生成されます。このクラスは DataFormat を実装し、データモデル内のプロパティが区切り文字によって分離されて順番に並んでいるようなテキストファイルを取り扱えます。

また、 単純な ファイルを入力に利用するDSL と ファイルを出力に利用するDSL の骨格も自動生成します。前者は <出力先パッケージ>.text.Abstract<データモデル名>CsvTextInputDescription 、後者は <出力先パッケージ>.text.Abstract<データモデル名>CsvTextOutputDescription というクラス名で生成します。必要に応じて継承して利用してください。

他のデータフォーマット機能との関係

Direct I/O でテキストファイルを扱うには、本書で説明する Direct I/O formatted text の他にも以下のような機能を利用できます。

Direct I/O CSV

Direct I/O TSV (非推奨機能)

Direct I/O line

これらの機能と Direct I/O formatted text では提供する機能の一部が重複、または類似しているため、以下ではそれぞれの機能のおおまかな差異や使い分けの指針を説明していきます。

Attention

ここで説明する内容は現時点のもので、将来のバージョンで変更される可能性があります。

Direct I/O CSV

Direct I/O CSV と Direct I/O formatted text ( @directio.text.csv ) は両者とも RFC 4180 [https://tools.ietf.org/html/rfc4180.html] で提唱されているCSVの形式に基づいたデータフォーマットを扱う機能です。

機能面では、 Direct I/O formatted text は Direct I/O CSV よりも細かいデータフォーマットの指定が可能で、不整合データの取り扱いも柔軟に設定することができます。 Direct I/O CSV を利用する場合には事前にフォーマット整形が必要となるようなケースでは、Direct I/O formatted text によってより効率のよい対応が可能となる場合があります。

性能面では、現時点において Direct I/O CSV は Direct I/O formatted text よりも高速に動作します。パフォーマンス差異の度合いは実行環境や扱うファイルの特性にも変わりますが、手元の検証ではおおよそ20%から30%程度、 Direct I/O CSV のほうが高速に動作するようです。

これらの機能の特性を考慮し、また実際に取り扱うデータフォーマットや実行環境の特性に応じて機能を選択するとよいでしょう。

Direct I/O TSV

Direct I/O TSV は TSV形式のデータフォーマットを使う機能ですが、 TSV形式のデータフォーマットについては Direct I/O formatted text を利用することを推奨します。

Direct I/O TSV は本バージョンでは非推奨機能です。その主な理由は本機能で対応可能なデータフォーマットが制限的で、汎用性に乏しいことによります。また不整合データの取り扱いについても他のデータフォーマット機能と比べて劣る部分があります。

なお、現時点で今後 Direct I/O TSV に関して大幅な拡張や変更を行う予定はありません。

Direct I/O line

Direct I/O line はファイル内の行文字列とデータモデル内の1つの文字列型プロパティをマッピングするシンプルな機能を提供します。

Direct I/O lineが想定する用途は主に2つあり、1つは JSON [http://json.org] や LTSV [http://ltsv.org] といった、レコードが1行で表現されるがデータの構成に区切り文字やフィールドの位置以外を利用するテキストデータフォーマットを取り扱う場合です。このような用途では引き続き Direct I/O line の利用を推奨します。

もう1つは、CSVやTSV形式の入力ファイルを扱いたいが、Direct I/O CSV や Direct I/O TSV が提供する機能では直接扱うことができず、テキスト内容の整形や形式変換、バリデーションチェックなどの事前処理が必要となる場合です。このようなケースのいくつかは Direct I/O formatted text が提供する機能によって、直接データを扱うことが可能となる場合があります。

データフォーマットの設定

@directio.text.tabular および @directio.text.csv 属性の要素には、データフォーマットに関する次のような設定を指定することができます。

テキスト全体の構成

ファイルヘッダの構成

データ型の形式

入力時の動作

出力時の動作

エスケープ方式 ( @directio.text.tabular のみ )

クウォート方式 ( @directio.text.csv のみ )

ここで指定する設定項目のうち、データフィールドに対して適用される設定については、全てのデータフィールドに共通の設定値として適用されます。データフィールド単位で個別に設定を指定したい場合は、 後述の データフィールドの設定 を行うことでデータフィールド単位に設定を上書きすることができます。

以下はDMDLスクリプトの記述例です。

@directio.text.tabular(
    charset = "ISO-2022-JP",
    header = force,
    compression = "gzip",
    true_format = "1",
    false_format = "0",
    date_format = "yyyy/MM/dd",
    datetime_format = "yyyy/MM/dd HH:mm:ss",
)
model = {
    ...
};

テキスト全体の構成

charset

ファイルの文字セットエンコーディングを表す文字列。

指定した文字セットエンコーディングが ASCII または ASCIIの上位互換 のいずれでもない場合、 入力データの分割 が行われなくなる。

既定値: "UTF-8"

compression

ファイルの圧縮形式。 "gzip" または CompressionCodec 1 のサブタイプのクラス名を指定する。

ここで指定した圧縮形式で対象のファイルが読み書きされるようになるが、代わりに 入力データの分割 が行われなくなる。

既定値: 未指定 (圧縮無し)

line_separator

ファイル出力時に使用する、レコード間を区切るテキストの改行文字。以下のオプションから指定する。

unix : LF のみ

windows : CRLF の組み合わせ

入力時にはこの設定を利用せず、 LF, CR, CRLF のいずれも改行として扱う。ただし CR のみの場合には 入力データの分割 が行われなくなる。

入力の末尾に改行文字が出現した場合、EOFとして扱う(次行を空レコードとして取り扱わない)。

既定値:

@directio.text.tabular : unix

@directio.text.csv : windows

field_separator

フィールド間の区切り文字。任意の1文字を指定する。

"\r" (CR), "\n" (LF), 及び escape_character で指定した値は指定できない。

既定値:

@directio.text.tabular : "\t" (HT:水平タブ)

@directio.text.csv : "," (カンマ)

1

org.apache.hadoop.io.compress.CompressionCodec

ファイルヘッダの構成

header

ファイルヘッダの処理方法。以下のオプションから指定する。

nothing : 何もしない

force : 入力時に先頭行をスキップし、出力時に先頭行にヘッダを出力する

skip : 入力時に先頭行がヘッダにマッチすればスキップし、出力時はヘッダを出力しない

auto : 入力時に先頭行がヘッダにマッチすればスキップし、出力時に先頭行にヘッダを出力する

既定値: nothing

データ型の形式

true_format

データモデルの論理値型 ( BOOLEAN ) で TRUE を表す文字列。

false_format , null_format と同じ文字列は使用できない。

trim_input を利用した場合、 true_format の前後に空白文字が含まれているとマッチしない。

既定値: "true"

false_format

データモデルの論理値型 ( BOOLEAN ) で FALSE を表す文字列。

true_format , null_format と同じ文字列は使用できない。

trim_input を利用した場合、 false_format の前後に空白文字が含まれているとマッチしない。

既定値: "false"

number_format

データモデルの数値型 ( INT , LONG , FLOAT , DOUBLE , DECIMAL , BYTE , SHORT ) の形式。 DecimalFormat 2 の形式で指定する。

null を指定した場合は未指定として扱う。未指定の場合はDirect I/O formatted textが規定する標準の方式で解析、及び出力を行う。

既定値: 未指定

decimal_output_style

データモデルの10進数型 ( DECIMAL ) の出力形式。以下のオプションから指定する。

plain : 指数表現なし

scientific : 必要ならば、指数表現を 10^n の単位で行う

engineering : 必要ならば、指数表現を 10^(n*3) の単位で行う

入力時にはこの設定を利用せず、全ての形式に対応する。

該当フィールドに number_format が指定されている場合、 decimal_output_style で指定した内容は無視される。

既定値: scientific

date_format

データモデルの日付型 ( DATE ) の形式。 SimpleDateFormat 3 の形式で指定する。

既定値: "yyyy-MM-dd"

datetime_format

データモデルの日時型 ( DATETIME ) の形式。 SimpleDateFormat の形式で指定する。

既定値: "yyyy-MM-dd HH:mm:ss"

null_format

NULL 値を表す形式。任意の文字列を指定する。

null を指定した場合は未指定として扱う。

NULL 値が未指定の場合、以下のような動作となる。

入力データには NULL を表す値を含められない。

出力データに NULL が含まれる場合には on_unmappable_output の設定に従ってエラー処理を行い、その結果ファイルの出力が実行される場合には、空文字列が出力される。

@directio.text.tabular を利用する場合には、 null 値の指定は escape_sequence の設定も利用される。その場合の動作を以下に示す。

null_format が未指定である場合、 escape_sequence で定義した null 値の設定を利用する。

escape_sequence でも null 値が未指定の場合、上記に示す「 NULL 値が未指定の場合」と同じ動作となる。

null_format と escape_sequence に両方 null 値が設定されている場合、 null_format の設定が優先して利用される。

既定値: 未指定

2

java.text.DecimalFormat

3

java.text.SimpleDateFormat

入力時の動作

trim_input

入力時に、フィールドの先頭末尾の空白文字を除去するかどうか。以下のオプションから指定する。

true : 除去する

false : 除去しない

この操作によってフィールドが空になった場合、 skip_empty_input の対象となる。

既定値: false

skip_empty_input

入力時に、フィールドの文字列が空である場合の動作。以下のオプションから指定する。

true : 読み飛ばす

false : 空文字列として扱う

既定値: false

on_malformed_input

入力時に、不正なフィールド文字列が検出された場合の動作。以下のオプションから指定する。

error : エラーログを出力して、異常終了する。

report : 警告ログを出力して、プロパティに NULL を設定する。

ignore : プロパティに NULL を設定する。

既定値: error

on_more_input

入力時に、レコードに余剰フィールドが検出された場合の動作。以下のオプションから指定する。

error : エラーログを出力して、異常終了する。

report : 警告ログを出力して、余剰フィールドを無視する。

ignore : 余剰フィールドを無視する。

既定値: error

on_less_input

入力時に、レコードにフィールドが不足している場合の動作。以下のオプションから指定する。

error : エラーログを出力して、異常終了する。

report : 警告ログを出力して、プロパティに NULL を設定する。

ignore : プロパティに NULL を設定する。

既定値: error

出力時の動作

on_unmappable_output

出力時に、不正な文字が含まれている場合の動作。以下のオプションから指定する。

error : エラーログを出力して、異常終了する。

report : 警告ログを出力して、そのまま出力。

ignore : そのまま出力。

データ内にエスケープやクウォートで対処できないメタ文字や、マッピングが未指定で NULL が存在した場合などに該当する。

既定値: error

エスケープ方式

エスケープ方式の設定は、 @directio.text.tabular 属性に対してのみ有効。

escape_character

エスケープシーケンス(エスケープ文字＋後続文字)で使用するエスケープ文字。任意の1文字を指定する。

"\r" , "\n" , 及び field_separator で指定した値は指定できない。

既定値: 未指定 (エスケープシーケンスを利用できない)

escape_line_separator

改行文字をエスケープ可能にするかどうか。以下のオプションから指定する。

true - 改行文字をエスケープ可能にする。このオプションを指定した場合、 入力データの分割 が行われなくなる。

false - 改行文字をエスケープ不可能にする。

この設定を利用するには escape_character も定義する必要がある。

既定値: false

escape_sequence

利用可能なエスケープの一覧。マップ形式 ( { "キー":"値", "キー":"値", ... } ) で指定する。

キー

キーにはエスケープシーケンスの後続文字(エスケープ文字を除いた1文字)を指定する。

キーには "\r" , "\n" といった、改行文字の構成要素を含められない。改行文字のエスケープするための設定は escape_line_separator で指定する。

値

値にはシーケンスに対応する1文字を指定する。

値にはNULLを表す特別なシンボル null を利用出来る。フィールド全体がそのシーケンスのみの値である場合、そのフィールド値はNULLとしてエスケープされる。

サロゲートペアはキー・値のいずれにも利用できない。

この設定を利用するには escape_character も定義する必要がある。

既定値: なし

クウォート方式

クウォート方式の設定は、 @directio.text.csv 属性に対してのみ有効。

quote_character

フィールドのクウォートで使用するクウォート文字。

"\r" , "\n" , 及び field_separator で指定した値は指定できない。

既定値: "\"" (ダブルクウォート)

allow_linefeed

フィールドにLF(改行文字)を含められるかどうか。以下のオプションから指定する。

true : 含められる。このオプションを指定した場合、 入力データの分割 が行われなくなる。

false : 含められない。フィールドにLFが含まれる場合はエラーとして扱う。

既定値: false

quote_style

出力時のクォート方式。以下のオプションから指定する。

always : 常にクウォートを行う。

never : 常にクウォートを行わない。フィールドに CR, LF, field_separator, quote_character のいずれかが含まれる場合はエラーとして扱う。

needed : フィールドに CR, LF, field_separator, quote_character のいずれかが出現した場合のみクウォートを行う。

入力時にはこの設定を利用せず、全てのクウォート方式に対応する。

既定値: needed

header_quote_style

出力時ヘッダのクォート方式。以下のオプションから指定する。

always : 常にクウォートを行う。

never : 常にクウォートを行わない。フィールドに CR, LF, field_separator, quote_character のいずれかが含まれる場合はエラーとして扱う。

needed : フィールドに CR, LF, field_separator, quote_character のいずれかが出現した場合のみクウォートを行う。

入力時にはこの設定を利用せず、全てのクウォート方式に対応する。

未指定の場合、 quote_style と同じクウォート方式を利用する。

既定値: 未指定

データフィールドの設定

Direct I/O formatted text が扱うテキストファイルのデータフィールドに関する設定は、DMDLスクリプトのデータモデルに含まれるそれぞれのプロパティに @directio.text.field 属性を指定します。

@directio.text.field 属性の要素には、次のような設定を指定することができます。

フィールドの基本情報

フィールドのデータフォーマット

その他、データフィールドに対する個別の属性を利用した、次のような設定を指定することができます。

フィールドの除外

ファイル情報の取得

以下はDMDLスクリプトの記述例です。

@directio.text.tabular (
    ...
)
model = {
    @directio.text.field (
        name = "数量",
        null_format = "",
        on_unmappable_output = report,
    )
    amount : INT;
};

フィールドの基本情報

name

フィールド名を表す文字列。

header の設定によりファイルヘッダを出力する場合、ここで指定したフィールド名がヘッダに利用される。未指定の場合、プロパティ名がヘッダに利用される。

既定値: 未指定

フィールドのデータフォーマット

データフォーマットの設定 が持つ設定のうち、次の項目については @directio.text.field 属性に同名の要素を指定することでデータフィールド単位に設定を上書きすることができます。

データ型の形式

true_format

false_format

number_format

decimal_output_style

date_format

datetime_format

null_format

入力時の動作

trim_input

skip_empty_input

on_malformed_input

出力時の動作

on_unmappable_output

クウォート方式

quote_style ( @directio.text.csv 内のプロパティのみ )

フィールドの除外

データモデルに定義されている特定のプロパティをデータフィールドとして取り扱いたくない場合の設定です。

@directio.text.ignore

このプロパティをデータフィールドとして取り扱わない。

ファイル情報の取得

入力時のテキストファイルに関する情報を取得する場合、それぞれ次の属性をプロパティに指定します。

これらの属性はファイル入力時のみ有効です。これらの属性を指定したプロパティは、ファイル出力時にはデータフィールドから除外されます。

@directio.text.file_name

このフィールドに、該当データレコードが含まれるファイルパスを設定する。

この属性を指定するプロパティには TEXT 型を指定する必要がある。

@directio.text.line_number

このフィールドに、該当データレコードの開始行番号（テキスト行番号）を設定する。

この属性を指定するプロパティには INT または LONG 型を指定する必要がある。

この属性が指定された場合、 入力データの分割 が行われなくなる。

@directio.text.record_number

このフィールドに、該当データレコードのレコード番号を設定する。

この属性を指定するプロパティには INT または LONG 型を指定する必要がある。

この属性が指定された場合、 入力データの分割 が行われなくなる。

設定例

エスケープシーケンス

@directio.text.tabular でエスケープシーケンスを利用するための設定例です。ここでは以下のようなエスケープシーケンスを定義します。

\ をエスケープ文字に指定

改行文字 \r , \n , タブ \t をエスケープ

エスケープ文字自体をエスケープ

\N をNULLとして扱う

@directio.text.tabular (
    escape_character = "\\",
    escape_sequence = {
      "r" : "\r",
      "n" : "\n",
      "t" : "\t",
      "\\" : "\\",
      "N" : null,
    },
)
...

Note

DMDLスクリプト内ではJavaの文字列リテラルと同様に \ はエスケープシーケンスとして扱われるため、各要素の値に \ を指定したい場合は "\\" のようにバックスラッシュを2つ記述します。

空文字列とNULLの扱い

Direct I/O formatted textでは、空文字列とNULLに関して標準では以下のように設定されています。

skip_empty_input = false (フィールド値が空値の場合は空文字列として扱う)

null_format = (未指定)

これらの設定により、標準の動作は以下のような強い制約を伴います。

入力ファイル内のフィールド値が空文字列となっている場合、そのフィールドが TEXT 型以外のプロパティと対応付けられていると不正な値として扱われる。

出力時にデータモデル内のプロパティ値に null が含まれると不正な値として扱われる。

データモデル全体で空文字列を NULL として扱う場合は、以下のように null_format を設定します。

@directio.text.csv (
    null_format = "",
)
...

Note

上記のデータモデル全体で空文字列を NULL として扱う動作は Direct I/O CSV と同じ動作となります。 Direct I/O CSV から Direct I/O formatted text ( @directio.text.csv ) に移行するなどで、 Direct I/O CSV と同様の動作に設定したい場合には上例のように設定してください。

数値型のプロパティのみに対して空文字列を NULL として扱うなど、フィールド単位で null_format を設定することもできます。

@directio.text.csv (
    ...
)
model = {
    @directio.text.field (
        null_format = "",
    )
    amount : INT;
};

null_format による設定のほかに、不正な値を検出した場合の動作を変更し処理を続行させる方法もあります。以下の設定は、数値型のフィールドに空文字列などの不正なフォーマットを検出した場合に警告を出力し、空文字列と null を相互にマッピングします。

@directio.text.csv (
    ...
)
model = {
    @directio.text.field (
        on_malformed_input = report,
        on_unmappable_output = report,
    )
    amount : INT;
};

Attention

null_format が未指定の場合、テストドライバのジョブフローやバッチのテスト実行時にテストドライバが NULL を取り扱う動作にも注意が必要です。

例えば Excelによるテストデータ定義 などの方法で入力データを定義する際には、テストケースで利用しないプロパティを未定義にすることができますが、その際テストドライバは未定義のプロパティをNULLとして取り扱います。また同様に空のセルもNULLとして扱います。

テストドライバの NULL 値の扱いについては、 Excelによるテストデータ定義 などのテストドライバのドキュメントを確認してください。

Direct I/O JSON

この文書では、Direct I/OでJSON形式 1 および JSON Lines形式 2 のテキストファイルを取り扱うための機能「Direct I/O JSON」について説明します。

Experimental

Asakusa Framework バージョン 0.10.3 では、 Direct I/O JSON は試験的機能として提供しています。

1

http://json.org/

2

http://jsonlines.org/

概要

Direct I/O JSONでは、Direct I/OでJSON形式を持つテキストファイルを読み書きするための汎用的な機能を提供します。

また、JSON Linesと呼ばれる、JSONの1レコードを1行で格納し、レコード間を改行で区切る形式 2 もサポートしています。 JSON Lines形式の入力ファイルは分割して処理を行うことができるため、通常のJSON形式に比べて高速にファイルの入力処理を実行できる可能性があります。

Direct I/O JSONで出力するファイルの形式は、JSON Lines形式となります。

データフォーマットの作成

Direct I/O JSONを利用するには、DMDLに対してDirect I/O JSONを利用することを示す拡張属性 @directio.json を追加します。

JSON形式のファイルに対応するデータモデルを定義するDMDLスクリプトの例は、以下のようになります。

@directio.json
document = {
    "the name of this document"
    name : TEXT;

    "the content of this document"
    content : TEXT;
};

また、JSON Lines形式のファイルとして読み込む場合、@directio.json に対して属性 format = jsonl を指定します。

@directio.json (
    format = jsonl
)
document = {
    "the name of this document"
    name : TEXT;

    "the content of this document"
    content : TEXT;
};

上記のように記述してデータモデルクラスを生成すると、 <出力先パッケージ>.json.<データモデル名>JsonFormat というクラスが自動生成されます。このクラスは DataFormat を実装し、JSON形式のテキストファイルを取り扱えます。

また、 単純な ファイルを入力に利用するDSL と ファイルを出力に利用するDSL の骨格も自動生成します。前者は <出力先パッケージ>.json.Abstract<データモデル名>JsonInputDescription 、後者は <出力先パッケージ>.json.Abstract<データモデル名>JsonOutputDescription というクラス名で生成します。必要に応じて継承して利用してください。

データフォーマットの設定

@directio.json 属性の要素には、データフォーマットに関する次のような設定を指定することができます。

テキスト全体の構成

データ型の形式

入力時の動作

ここで指定する設定項目のうち、JSONフィールドに対して適用される設定については、全てのJSONフィールドに共通の設定値として適用されます。 JSONフィールド単位で個別に設定を指定したい場合は、 後述の JSONフィールドの設定 を行うことでJSONフィールド単位に設定を上書きすることができます。

以下はDMDLスクリプトの記述例です。

@directio.json (
    format = jsonl,
    compression = "gzip",
    date_format = "yyyy/MM/dd",
    datetime_format = "yyyy/MM/dd HH:mm:ss",
    on_unknown_input = report
)
model = {
    ...
};

テキスト全体の構成

format

入力ファイルのJSON形式。以下のオプションから指定する。

json : JSON形式

jsonl : JSON Lines形式

jsonl を指定して、入力ファイルがJSON Linesの形式を満たしていない場合は正常にファイルの読み込みが行われないことがある。

出力ファイルの形式は常にJSON Lines形式となる。

既定値: json

charset

ファイルの文字セットエンコーディングを表す文字列。

指定した文字セットエンコーディングが ASCII または ASCIIの上位互換 のいずれでもない場合、 入力データの分割 が行われなくなる。

既定値: "UTF-8"

compression

ファイルの圧縮形式。 "gzip" または CompressionCodec 3 のサブタイプのクラス名を指定する。

ここで指定した圧縮形式で対象のファイルが読み書きされるようになるが、代わりに 入力データの分割 が行われなくなる。

既定値: 未指定 (圧縮無し)

line_separator

ファイル出力時に使用する、レコード間を区切るテキストの改行文字。以下のオプションから指定する。

unix : LF のみ

windows : CRLF の組み合わせ

入力時にはこの設定を利用せず、 LF, CR, CRLF のいずれも空白文字として扱う。

既定値: unix

3

org.apache.hadoop.io.compress.CompressionCodec

データ型の形式

date_format

データモデルの日付型 ( DATE ) の形式。 SimpleDateFormat 4 の形式で指定する。

既定値: "yyyy-MM-dd"

datetime_format

データモデルの日時型 ( DATETIME ) の形式。 SimpleDateFormat の形式で指定する。

既定値: "yyyy-MM-dd HH:mm:ss"

null_style

出力時に、 対象プロパティが NULL 値であった場合の、プロパティに対応するJSONフィールドの出力内容。以下のオプションから指定する。

value : フィールドの値に null をセットして出力する。

absent : フィールドを出力しない。

既定値: value

4

java.text.SimpleDateFormat

入力時の動作

on_malformed_input

入力時に、不正な値が検出された場合の動作。以下のオプションから指定する。

error : エラーログを出力して、異常終了する。

report : 警告ログを出力して、プロパティに NULL を設定する。

ignore : プロパティに NULL を設定する。

既定値: error

on_unknown_input

入力時に、データモデルのプロパティに対応しないキー文字列が検出された場合の動作。以下のオプションから指定する。

error : エラーログを出力して、異常終了する。

report : 警告ログを出力する。

ignore : 無視する。

既定値: error

on_missing_input

入力時に、データモデルのプロパティに対応するキー文字列が出現しなかった場合の動作。以下のオプションから指定する。

error : エラーログを出力して、異常終了する。

report : 警告ログを出力して、プロパティに NULL を設定する。

ignore : プロパティに NULL を設定する。

既定値: ignore

Attention

null_style に absent を指定し、かつ on_missing_input に error を指定した場合、 NULL 値を持つプロパティに対して対称性が失われるので注意が必要です。

上記の設定を持つデータモデルをJSONファイルとして出力する場合、NULL値を持つプロパティは null_style = absent によってJSONフィールドには含まれません。その後、出力したJSONファイルを同じデータモデルとして入力すると、プロパティに対応するJSONフィールドが存在しないこととなり、 on_missing_input = error によって異常終了となります。

JSONフィールドの設定

Direct I/O JSON が扱うテキストファイルのJSONフィールドに関する設定は、DMDLスクリプトのデータモデルに含まれるそれぞれのプロパティに @directio.json.field 属性を指定します。

@directio.json.field 属性の要素には、次のような設定を指定することができます。

フィールドの基本情報

フィールドのデータフォーマット

その他、JSONフィールドに対する個別の属性を利用した、次のような設定を指定することができます。

フィールドの除外

ファイル情報の取得

以下はDMDLスクリプトの記述例です。

@directio.json (
    ...
)
model = {
    @directio.json.field (
        name = "total_amount",
        null_style = absent,
        decimal_output_style = plain,
    )
    amount : DECIMAL;
};

フィールドの基本情報

name

JSONフィールド名を表す文字列。

この値とJSONキー文字列が一致するJSONフィールドが、この属性を指定したプロパティの入出力先となる。

既定値: 未指定

フィールドのデータフォーマット

データフォーマットの設定 が持つ設定のうち、次の項目については @directio.json.field 属性に同名の要素を指定することでJSONフィールド単位に設定を上書きすることができます。

データ型の形式

date_format

datetime_format

null_style

入力時の動作

on_malformed_input

on_missing_input

フィールドの除外

データモデルに定義されている特定のプロパティをJSONフィールドとして取り扱いたくない場合の設定です。

@directio.json.ignore

このプロパティをJSONフィールドとして取り扱わない。

ファイル情報の取得

入力時のテキストファイルに関する情報を取得する場合、それぞれ次の属性をプロパティに指定します。

これらの属性はファイル入力時のみ有効です。これらの属性を指定したプロパティは、ファイル出力時にはJSONフィールドから除外されます。

@directio.json.file_name

このフィールドに、該当データレコードが含まれるファイルパスを設定する。

この属性を指定するプロパティには TEXT 型を指定する必要がある。

@directio.json.line_number

このフィールドに、該当データレコードの開始行番号（テキスト行番号）を設定する。

この属性を指定するプロパティには INT または LONG 型を指定する必要がある。

この属性が指定された場合、 入力データの分割 が行われなくなる。

@directio.json.record_number

このフィールドに、該当データレコードのレコード番号を設定する。

この属性を指定するプロパティには INT または LONG 型を指定する必要がある。

この属性が指定された場合、 入力データの分割 が行われなくなる。

制限事項

Asakusa Framework バージョン 0.10.3 の Direct I/O JSON には、以下のような制限事項があります。

未対応のデータ型

Direct I/O JSON ではJSONの以下のデータ型を取り扱うことはできません。

配列

オブジェクト

入力となるJSONのフィールドにこれらのデータ型が含まれていた場合、不正な値が検出された場合と同じ動作となります。デフォルトの設定ではエラーとして異常終了しますが、 データフォーマットの設定 の on_malformed_input または on_unknown_input を適切に設定することにより、 JSONファイル全体、またはJSONフィールド単位でこの動作を変更することもできます。

Direct I/O line

Direct I/Oで任意のテキストファイルを行ごとに読み書きするための機能として、「Direct I/O line」を利用することができます。

Direct I/O lineはファイル内の行文字列とデータモデル内の1つの文字列型プロパティをマッピングする機能のみを提供します。行文字列の解析、生成などの処理はバッチアプリケーションの演算子として記述します。

Direct I/O lineは、以下のような用途に利用することを想定しています。

Direct I/Oが対応していないファイルフォーマットの入出力

例えば LTSV [http://ltsv.org] などのフォーマットを扱う場合に、行文字列をパースする処理と組み合わせて利用します。

入力ファイルの整形や形式変換、バリデーションチェックなどの事前処理

例えばCSVファイルの一部にDirect I/Oでは直接扱えないような形式が含まれる場合に、事前に形式の変換を行うといった用途で利用します。

データモデルクラスの生成

Direct I/O lineを利用するには、DMDLに対してDirect I/O lineを利用することを示す拡張属性 @directio.line を追加します。

シンプルな例

以下はDirect I/O lineと連携するデータモデル定義の最もシンプルな例です。

@directio.line
model = {
    line : TEXT;
};

データモデルに拡張属性 @directio.line を指定して、 TEXT 型のプロパティを1つだけ定義すると、このプロパティが行文字列の入出力対象として使用されます。

ファイル形式の設定

@directio.line 属性には、次のような要素を指定できます。

Direct I/O lineのファイル形式の設定

要素

型

既定値

内容

charset

文字列

"UTF-8"

ファイルの文字エンコーディング

compression

文字列

なし（非圧縮）

ファイルの圧縮コーデック

compression には、 "gzip" または org.apache.hadoop.io.compress.CompressionCodec のサブタイプのクラス名を指定します 1 。ここで指定した圧縮形式で対象のファイルが読み書きされるようになりますが、代わりにファイルの分割読み出しが行われなくなります。

以下はDMDLスクリプトの記述例です。

@directio.line(
    charset="ISO-2022-jp",
    compression="gzip",
)
model = {
    ...
};

1

org.apache.hadoop.io.compress.DefaultCodec などが標準で用意されています

改行文字について

Direct I/O lineでは、ファイル内の改行文字を以下のように扱います。

ファイルの入力時には CRLF または LF を改行文字として扱います。

ファイルの出力時には、 LF を改行文字として出力します。

モデルプロパティの設定

Direct I/O lineで利用できるモデルプロパティの設定について説明します。

以下は、モデルプロパティの設定を指定したDMDLスクリプトの記述例です。

@directio.line
model = {
    // 行文字列の格納(TEXT型)
    @directio.line.body
    body : TEXT;

    // ファイルパスの格納(TEXT型)
    @directio.line.file_name
    path : TEXT;

    // 行番号の格納(INTまたはLONG型)
    @directio.line.line_number
    num : INT;

    // その他のプロパティは無視
    other : TEXT;
};

行文字列用プロパティの指定

データモデル内で行文字列を格納するプロパティを指定するには、以下の属性をプロパティに指定します。

ファイル情報の取得に関する属性

属性

型

内容

@directio.line.body

TEXT

行文字列

データモデル内にプロパティが複数ある場合、この属性を付与したプロパティに行文字列が格納され、その他のプロパティは無視されます。 @directio.line.body を指定できるプロパティは1つのみです。

なお、データモデル内に TEXT 型を持つプロパティが1つのみ存在するようにデータモデルを定義した場合、 @directio.line.body を付与しなくても自動的にそのプロパティが行文字列を格納するプロパティとして自動認識されます。先述の シンプルな例 で示すデータモデルの例はこの自動認識の機能が利用されています。

Attention

行文字列のプロパティ値が null のデータモデルオブジェクトをファイルに出力した場合、行は追加されません。

ファイル情報の取得

解析中のファイルに関する属性を取得する場合、以下の属性をプロパティに指定します。

ファイル情報の取得に関する属性

属性

型

内容

@directio.line.file_name

TEXT

ファイル名

@directio.line.line_number

INT , LONG

テキスト行番号 (1起算)

Attention

@directio.line.line_number が指定された場合、 入力データの分割 が行われなくなります。

Attention

これらの属性はファイルを読み込みの解析時のみ有効です。ファイルを書き出す際には無視されます。

データモデルクラス生成コマンド

データモデルクラスの生成は通常のDMDLで提供する方法と同様に、Gradleの compileDMDL タスクを実行して生成します。

./gradlew compileDMDL

Asakusa DSLの記述

Direct I/O lineを使った場合のAsakusa DSLの記述については、基本的な流れは他のデータフォーマットを使った場合と同様です。詳しくは、 Direct I/O スタートガイド などを参照してください。

以下ではAsakusa DSLの記述に関して、Direct I/O lineと他のデータフォーマットで異なる部分についてのみ説明します。

ファイルシステム上のファイルを入力に利用する

処理対象のファイルをインポートしてHadoopの処理を行う場合、 データモデルクラスの生成 で生成した <パッケージ名>.line.Abstract<データモデル名>LineInputDescription クラスのサブクラスを作成して必要な情報を記述します。

ファイルシステム上にファイルを出力する

ジョブフローの処理結果をファイルにエクスポートする場合、 データモデルクラスの生成 で生成した <パッケージ名>.line.Abstract<データモデル名>LineOutputDescription クラスのサブクラスを作成して必要な情報を記述します。

Direct I/O sequence file

この文書では、Direct I/OからHadoopのシーケンスファイルをインポート/エクスポートする方法について説明します。

シーケンスファイル形式のDataFormatの作成

Hadoopのシーケンスファイル 1 を直接読み書きするには、 SequenceFileFormat 2 のサブクラスを作成します。

Hint

以降の記述は、Asakusa Frameworkの外部で作成されたシーケンスファイルを利用する際の方法です。シーケンスファイルにAsakusa Frameworkのデータモデル形式を直接利用する場合 内部データ形式を利用したシーケンスファイル形式のDataFormatの作成 なども利用可能です。

SequenceFileFormat は HadoopFileFormat のサブクラスで、シーケンスファイルを読み書きするための骨格実装が提供されています。

このクラスを継承する際には、以下の型引数を SequenceFileFormat<K, V, T> にそれぞれ指定してください。

K

対象シーケンスファイルのキーオブジェクトの型

V

対象シーケンスファイルの値オブジェクトの型

T

アプリケーションで利用するデータモデルオブジェクトの型

このクラスでは、下記のメソッドをオーバーライドします。

Class<T> getSupportedType()

対象となるデータモデルのクラスを戻り値に指定します。

K createKeyObject()

対象のシーケンスファイルのキーと同じクラスのオブジェクトを戻り値に指定します。

V createValueObject()

対象のシーケンスファイルの値と同じクラスのオブジェクトを戻り値に指定します。

void copyToModel(K key, V value, T model)

シーケンスファイルから読み出したキー ( key ) と 値 ( value ) の内容を、対象のデータモデルオブジェクト ( model ) に設定します。

このメソッドは、シーケンスファイルからデータ読み出す際に、レコードごとに起動されます。このメソッドによって変更されたデータモデルオブジェクトは、以降の処理の入力として利用されます。

void copyFromModel(T model, K key, V value)

結果を表すデータモデルオブジェクトの内容を、シーケンスファイルのキー ( key ) と値 ( value ) に設定します。

このメソッドは、シーケンスファイルにデータを書き込む際に、レコードごとに起動されます。このメソッドによって変更されたキーと値がそのままシーケンスファイルに書き出されます。

CompressionCodec getCompressionCodec(Path path)

シーケンスファイルの作成時に利用する圧縮コーデックを指定します。

オーバーライドしない場合、全体の設定情報をもとに圧縮コーデックを決定します。詳しくは シーケンスファイルの圧縮 を参照してください。

以下はシーケンスファイル形式のDataFormatの実装例です。

public class ExampleSequenceFormat extends SequenceFileFormat<LongWritable, Text, MyData> {

    @Override
    public Class<MyData> getSupportedType() {
        return MyData.class;
    }

    @Override
    protected LongWritable createKeyObject() {
        return new LongWritable();
    }

    @Override
    protected Text createValueObject() {
        return new Text();
    }

    @Override
    protected void copyToModel(LongWritable key, Text value, MyData model) {
        model.setPosition(key.get());
        model.setText(value);
    }

    @Override
    protected void copyFromModel(MyData model, LongWritable key, Text value) {
        key.set(model.getPositionOption().or(0L));
        value.set(model.getTextOption().or("(null)"));
    }
}

Hint

この機能は、 Apache Sqoop [http://sqoop.apache.org/] 等のツールと連携することを想定して提供されています。

1

org.apache.hadoop.io.SequenceFile

2

com.asakusafw.runtime.directio.hadoop.SequenceFileFormat [https://docs.asakusafw.com/0.10.3/release/api/com/asakusafw/runtime/directio/hadoop/SequenceFileFormat.html]

シーケンスファイルの圧縮

SequenceFileFormat を利用してシーケンスファイルを作成する場合、以下のいくつかの方法で圧縮形式を指定できます。以下、上から順に該当する項目があれば、そこで設定された圧縮形式を利用します。

SequenceFileFormat.getCompressionCodec(Path path) をオーバーライド

オーバーライドしたメソッドが返す圧縮コーデックを利用します。

null を指定した場合、圧縮は行われません。

設定ファイルで com.asakusafw.output.sequencefile.compression.codec を指定

上記の設定値に CompressionCodec 3 を実装したクラス名を指定すると、その圧縮コーデックを利用します。

なお、利用する圧縮コーデックはあらかじめHadoopクラスターの全台に導入されている必要があります。

上記いずれの指定もない場合、シーケンスファイルの圧縮を行いません。

Note

上記の設定はシーケンスファイル作成時のみ有効です。シーケンスファイルを読み出す際には、シーケンスファイルの圧縮形式を自動的に判別します。

3

org.apache.hadoop.io.compress.CompressionCodec

内部データ形式を利用したシーケンスファイル形式のDataFormatの作成

シーケンスファイル対し、Asakusa Frameworkで利用するデータモデル形式を直接保存したり復元したりするような DataFormat の実装クラスを自動的に生成するには、対象のデータモデルに @directio.sequence_file を指定します。

@directio.sequence_file
document = {
    "the name of this document"
    name : TEXT;

    "the content of this document"
    content : TEXT;
};

上記のように記述してデータモデルクラスを生成すると、 <出力先パッケージ>.sequencefile.<データモデル名>SequenceFileFormat というクラスが自動生成されます。このクラスは DataFormat を実装し、対象のデータモデルオブジェクトをHadoopの直列化機構を直接利用したシーケンスファイルを取り扱えます。

また、 単純な ファイルを入力に利用するDSL と ファイルを出力に利用するDSL の骨格も自動生成します。前者は <出力先パッケージ>.sequencefile.Abstract<データモデル名>SequenceFileInputDescription 、後者は <出力先パッケージ>.sequencefile.Abstract<データモデル名>SequenceFileOutputDescription というクラス名で生成します。必要に応じて継承して利用してください。

Attention

シーケンスファイルの形式や、内部データのバイナリ表現はHadoopやAsakusa Frameworkのメジャーバージョンアップの際に変更になる場合があります。データを長期にわたって保管する場合、CSVなどのポータブルな形式を利用することを推奨します。

Hint

この機能を利用するには、DMDLコンパイラのプラグインに asakusa-directio-dmdl を追加する必要がありますが、 Asakusa Gradle Plugin ユーザーガイド の手順に従ってプロジェクトテンプレートから作成したプロジェクトは、これらのライブラリやプラグインがGradle Pluginによってデフォルトで利用可能になっています。

Hint

DMDLのデータモデル定義で、同一のデータモデルに @directio.csv と @directio.sequence_file の両方を指定することもできます。

Hint

シーケンスファイルの中身をテキスト形式で確認する場合、以下のコマンドを利用すると便利です。

hadoop fs -libjars "$ASAKUSA_HOME/core/lib/asakusa-runtime-all.jar,$ASAKUSA_HOME/batchapps/<バッチID>/lib/jobflow-<フローID>.jar" -text "<path/to/sequence-file>"

Direct I/O Hive

この文書では、Direct I/Oを使って Apache Hive [https://hive.apache.org/] （以下「Hive」）が対応するカラムナフォーマットのファイルを読み書きする方法について説明します。

Experimental

Asakusa Framework バージョン 0.10.3 では、Direct I/O のHive連携機能は試験的機能として提供しています。

See also

Hiveの操作も含めたアプリケーション開発の全体の流れについては、 Asakusa FrameworkとHiveを連携して利用する も参照にしてください。

Hive連携モジュールの利用方法

Hive連携モジュールを使用する場合は build.gradle に対して以下の定義を追加します。

Hive連携モジュール用のアプリケーションSDKライブラリを依存関係に追加する

asakusafw ブロックに sdk.hive true を追加

デプロイ構成に対してDirect I/O Hive用の構成を有効化する

asakusafwOrganizer ブロックに hive.enabled true を追加

以下、 build.gradle の設定例です。

asakusafw {
    sdk.hive true
}

asakusafwOrganizer {
    hive.enabled true
}

上記の設定後、 installAsakusafw タスクを実行して開発環境のAsakusa Frameworkを再インストールします。

Eclipseを利用している場合は、 eclipse タスクを実行してEclipseのプロジェクト情報を再構成します。

Hiveのバージョンについて

Hive連携モジュールはHive実行ライブラリを使用します。 Asakusa Framework バージョン 0.10.3 の標準の設定では、以下のバージョンのHive実行ライブラリが含まれます。

org.apache.hive:hive-exec:1.2.2

実行環境のHiveとHive連携モジュールが利用するHive実行ライブラリのバージョンが異なる場合、データの互換性に対する注意が必要です。また、実行環境のHadoopのバージョンによっては、利用可能なHive実行ライブラリのバージョンに制限が発生することがあります 1 。

Hive連携モジュールのHive実行ライブラリのバージョンを変更するには、以下のように build.gradle を設定します。以下はHive実行ライブラリに org.apache.hive:hive-exec:2.3.4 を使用する例です。

asakusafw {
    sdk.hive = ['org.apache.hive:hive-exec:2.3.4']
}

asakusafwOrganizer {
    hive.enabled true
    hive.libraries = ['org.apache.hive:hive-exec:2.3.4']
}

Note

Asakusa on Sparkが使用する実行環境のSparkにHive実行ライブラリが含まれる場合、Spark側のHive実行ライブラリが優先して使用されることがあります。この場合、Asakusa Frameworkの実行環境に含まれるHive実行ライブラリは無視されます。

1

一例として、実行環境がHadoop3系の場合、Hive1系の実行ライブラリは使用できないことを確認しています。

カラムナフォーマットファイルの入出力

Direct I/OのHive連携モジュールを利用することで、Direct I/OからHiveが対応するカラムナフォーマットファイルの入出力を行うことができます。

Asakusa Frameworkのバージョン 0.10.3 では、Hiveが対応するカラムナフォーマットのうち、以下のフォーマットに対するファイルの入出力に対応しています。

ORC File [https://cwiki.apache.org/confluence/display/Hive/LanguageManual+ORC]

Parquet [https://cwiki.apache.org/confluence/display/Hive/Parquet]

データモデルクラスの生成

Direct I/O CSV と同様に、データモデルクラス、及びファイル形式をマッピングする DataFormat の実装クラスは、DMDLコンパイラの拡張を利用して自動的に生成できます。

これらの生成機能は、DMDLコンパイラのプラグイン asakusa-hive-dmdl によって提供されます。このコンパイラプラグインは上述の Hive連携モジュールの利用方法 の設定を行うことで利用することができます。

ORC File形式のDataFormatの作成

ORC File形式に対応した DataFormat の実装クラスを自動的に生成するには、対象のデータモデルに対応するDMDLスクリプトに @directio.hive.orc を指定します。

@directio.hive.orc
document = {
    "the name of this document"
    name : TEXT;

    "the content of this document"
    content : TEXT;
};

上記のように記述してデータモデルクラスを生成すると、 <出力先パッケージ>.hive.orc.<データモデル名>OrcFileFormat というクラスが自動生成されます。このクラスは DataFormat を実装し、データモデルに対応するORC Fileを取り扱えます。

また、 ファイルを入力に利用するDSL と ファイルを出力に利用するDSL の骨格も自動生成します。前者は <出力先パッケージ>.hive.orc.Abstract<データモデル名>OrcFileInputDescription 、後者は <出力先パッケージ>.hive.orc.Abstract<データモデル名>OrcFileOutputDescription というクラス名で生成します。必要に応じて継承して利用してください。

ORC File形式の設定

@directio.hive.orc 属性には、次のような要素を指定できます。

ORC File形式の設定

要素

型

既定値

内容

table_name

文字列

モデル名

Hiveメタストア上のテーブル名

field_mapping

文字列

position

ファイル入力時の カラム名のマッピング 方式。 name : 名前マッピング, position : 位置マッピング

on_missing_source

文字列

logging

ファイル入力時に入力ファイル内にカラムがない場合の動作。 ignore : 無視, logging : 警告ログの出力, fail : エラー

on_missing_target

文字列

logging

ファイル入力時にデータモデル内にカラムがない場合の動作。 ignore : 無視, logging : 警告ログの出力, fail : エラー

on_incompatible_type

文字列

fail

ファイル入力時に入力ファイルとデータモデルでカラム型に互換性がない場合の動作。 ignore : 無視, logging : 警告ログの出力, fail : エラー

format_version

文字列

ライブラリが持つ規定値

ファイル出力時に使用するORC Fileのバージョン (後方互換性向け)。 0.11 | 0.12

compression

文字列

snappy

ファイル出力時に使用する圧縮コーデック。 none | zlib | snappy | lzo

stripe_size

数値

67108864

ファイル出力時に使用するORC Fileのストライプサイズ(バイト数)

table_name には、Hive上のテーブル名を指定します。指定しない場合はデータモデル上のモデル名をテーブル名として使用します。

field_mapping 、 on_missing_source 、 on_missing_target は、Direct I/Oがファイルを読み込む際に使用するデータモデルとのマッピング方式と、マッピングできないカラムが存在した場合の動作をそれぞれ指定します。詳しくは後述の カラム名のマッピング を参照してください。

on_incompatible_type には、Direct I/Oがファイルを読み込む際にORC File上のカラムデータ型とデータモデルのプロパティの型が対応していない場合の動作を指定します。データモデルとHive、及び各ファイルフォーマットとのデータ型の対応については、 データ型のマッピング を参照してください。

format_version はDirect I/Oで作成するORC Fileのバージョンを、ファイルを読み込むHiveのバージョンに合わせて指定します。例えば、作成したファイルを Hive 0.11 で読む場合は、フォーマットバージョンに 0.11 と指定します。

以下はDMDLスクリプトの記述例です。

@directio.hive.orc(
    table_name = "tb_lineitem",
    field_mapping = "name",
    on_missing_source = "fail",
    on_missing_target = "fail",
    on_incompatible_type = "fail",
    format_version = "0.11",
    compression = "none",
    stripe_size = 67108864,
)
document = {
    ...
};

Parquet形式のDataFormatの作成

Parquet形式に対応した DataFormat の実装クラスを自動的に生成するには、対象のデータモデルに対応するDMDLスクリプトに @directio.hive.parquet を指定します。

@directio.hive.parquet
document = {
    "the name of this document"
    name : TEXT;

    "the content of this document"
    content : TEXT;
};

上記のように記述してデータモデルクラスを生成すると、 <出力先パッケージ>.hive.parquet.<データモデル名>ParquetFileFormat というクラスが自動生成されます。このクラスは DataFormat を実装し、データモデルに対応するParquetを取り扱えます。

また、 ファイルを入力に利用するDSL と ファイルを出力に利用するDSL の骨格も自動生成します。前者は <出力先パッケージ>.hive.parquet.Abstract<データモデル名>ParquetFileInputDescription 、後者は <出力先パッケージ>.hive.parquet.Abstract<データモデル名>ParquetFileOutputDescription というクラス名で生成します。必要に応じて継承して利用してください。

Parquet形式の設定

@directio.hive.parquet 属性には、次のような要素を指定できます。

Parquet形式の設定

要素

型

既定値

内容

table_name

文字列

モデル名

Hiveメタストア上のテーブル名

field_mapping

文字列

position

ファイル入力時の カラム名のマッピング 方式。 name : 名前マッピング, position : 位置マッピング

on_missing_source

文字列

logging

ファイル入力時に入力ファイル内にカラムがない場合の動作。 ignore : 無視, logging : 警告ログの出力, fail : エラー

on_missing_target

文字列

logging

ファイル入力時にデータモデル内にカラムがない場合の動作。 ignore : 無視, logging : 警告ログの出力, fail : エラー

on_incompatible_type

文字列

fail

ファイル入力時に入力ファイルとデータモデルでカラム型に互換性がない場合の動作。 ignore : 無視, logging : 警告ログの出力, fail : エラー

format_version

文字列

v1

ファイル出力時に使用するParquetのバージョン。 v1 | v2

compression

文字列

snappy

ファイル出力時に使用する圧縮コーデック。 uncompressed | gzip | snappy | lzo

block_size

数値

134217728

ファイル出力時に使用するParquetのブロックサイズ(バイト数)

data_page_size

数値

1048576

ファイル出力時に使用するParquetのページサイズ(バイト数)

dictionary_page_size

数値

1048576

ファイル出力時に使用するParquetのディクショナリページサイズ(バイト数)

enable_dictionary

論理値

TRUE

ファイル出力時にParquetのディクショナリエンコーディングを使用するか。 TRUE :使用する, FALSE :使用しない

enable_validation

論理値

FALSE

ファイル出力時にParquetのデータスキーマの検査を行うか。 TRUE :検査する, FALSE :検査しない

table_name には、Hive上のテーブル名を指定します。指定しない場合はデータモデル上のモデル名をテーブル名として使用します。

field_mapping 、 on_missing_source 、 on_missing_target は、Direct I/Oがファイルを読み込む際に使用するデータモデルとのマッピング方式と、マッピングできないカラムが存在した場合の動作をそれぞれ指定します。詳しくは後述の カラム名のマッピング を参照してください。

on_incompatible_type には、Direct I/Oがファイルを読み込む際にParquet上のカラムデータ型とデータモデルのプロパティの型が対応していない場合の動作を指定します。データモデルとHive、及び各ファイルフォーマットとのデータ型の対応については、 データ型のマッピング を参照してください。

以下はDMDLスクリプトの記述例です。

@directio.hive.parquet(
    table_name = "tb_lineitem",
    field_mapping = "name",
    on_missing_source = "fail",
    on_missing_target = "fail",
    on_incompatible_type = "fail",
    format_version = "v2",
    compression = "uncompressed",
    block_size = 134217728,
    data_page_size = 1048576,
    dictionary_page_size = 1048576,
    enable_dictionary = TRUE,
    enable_validation = FALSE
)
document = {
    ...
};

モデルプロパティとカラムのマッピング

データモデルのプロパティと各カラムナフォーマットのカラムとの対応付けについては、データモデルの要素やモデルプロパティの属性を指定することで様々な対応方法を設定することができます。

カラム名のマッピング

データモデルのプロパティとカラムナフォーマットのカラムとのマッピングには 位置マッピング と 名前マッピング の2種類のマッピング方法があります。

位置マッピング

位置マッピングはデータモデル内のプロパティ定義の順番でカラムナフォーマットのカラムとの対応を行います。位置マッピングは Direct I/O CSV のマッピング方法と同様の方法です。

位置マッピングを行うには、データモデルの要素 field_mapping の値に position を指定します。

名前マッピング

名前マッピングはデータモデルのプロパティ名とカラムナフォーマットが保持するカラム名で対応を行います。

名前マッピングを行うには、データモデルの要素 field_mapping の値に name を 指定します。

データモデルのプロパティ名と異なる名前でカラムナフォーマットと名前マッピングを行いたい場合は、それぞれのモデルプロパティに @directio.hive.field 属性を指定し、さらに name 要素でフィールド名を指定します。

以下は名前マッピングの定義を付加したDMDLスクリプトの記述例です。

@directio.hive.orc
document = {
    "the name of this document"
    @directio.hive.field(name = "doc_name")
    name : TEXT;

    "the content of this document"
    @directio.hive.field(name = "doc_content")
    content : TEXT;
};

マッピング失敗時の動作

ファイル入力時にデータモデルのモデルプロパティとカラムナフォーマットファイルのカラム間の対応付けができなかった場合の動作は、データモデルの要素 on_missing_source と on_missing_target で指定します。

on_missing_source はデータモデルのプロパティ名に対して、入力ファイル内にカラムがない場合の動作を指定します。 on_missing_target は反対に、入力ファイル内のカラムに対して、データモデルのプロパティがない場合の動作を指定します。

各要素の値にはそれぞれ以下の値を設定することができます。

ignore : マッピングの失敗を無視して処理を続行

logging : マッピングが失敗したことを示す警告ログを出力して処理を続行

fail : エラーとしてバッチ処理を異常終了

Attention

ORC FileをHiveで生成する際に、利用するHiveのバージョンによってはファイルにカラム名の情報が出力されないようです。この場合、名前マッピングは利用できないため、位置マッピングの機能を利用する必要があります。

Hint

ORC Fileにカラム情報が出力されているかどうかを確認する方法として、ORC File Dump Utility を利用することができます。このツールはHive CLIが利用できる環境で以下のコマンドを実行します。

hive --orcfiledump <hdfs-location-of-orc-file>

データ型のマッピング

モデルプロパティのデータ型とカラムナフォーマットのデータ型との対応については、以下の2つのマッピングを考慮する必要があります。

モデルプロパティとHiveデータ型とのマッピング

Hiveデータ型とカラムナフォーマットのデータ型とのマッピング

たとえばあるデータ型について、a.のマッピングは対応しているが、b.のマッピングは対応していない、という場合にはそのままではそのプロパティを扱うことはできません。

そのような場合に、異なるデータ型としてそのプロパティを扱うための マッピング型変換機能 を提供しています。これは、a.のモデルプロパティとHiveデータ型とのマッピングにおいて、標準のデータ型のマッピングとは異なるデータ型へのマッピングを行う機能です。これによりそのプロパティを取り扱うことを可能にしています。

モデルプロパティとHiveデータ型とのマッピング

モデルプロパティとHiveデータ型のマッピング定義は以下の通りです。

モデルプロパティとHiveデータ型のマッピング

DMDL 2

Hive (標準マッピング) 3

Hive (マッピング型変換) 4

備考

INT

INT

-

LONG

BIGINT

-

FLOAT

FLOAT

-

DOUBLE

DOUBLE

-

TEXT

STRING

VARCHAR

CHAR

DECIMAL

DECIMAL

DECIMAL(精度とスケールの指定)

STRING

DATE

DATE

TIMESTAMP

STRING

DATETIME

TIMESTAMP

STRING

Hiveの TIMESTAMP 型が保持するミリ秒以下の情報はマッピング時に切り捨て

BOOLEAN

BOOLEAN

-

BYTE

TINYINT

-

SHORT

SMALLINT

-

Attention

上表で記載が無いHiveデータ型( BINARY 、及び ARRAY などの Complex Types）には対応していません。

Attention

Hiveの TIMESTAMP 型はタイムゾーンを保持しません。複数の異なるタイムゾーンを持つ環境間で TIMESTAMP 型を持つデータを扱う場合、タイムゾーンの差異によって異なる値が扱われる可能性があることに注意してください。

2

DMDLで指定するプロパティの型です。詳しくは DMDLユーザーガイド を参照してください

3

モデルプロパティの型に対して、標準で対応するHiveのデータ型です。 Hiveのデータ型について詳しくはHiveのドキュメント LanguageManual Types [https://cwiki.apache.org/confluence/display/Hive/LanguageManual+Types] などを参照してください。

4

モデルプロパティの型に対して、 マッピング型変換機能 が対応するHiveのデータ型です。

マッピング型変換機能

マッピング型変換機能は、Direct I/Oがカラムナフォーマットのファイルを入出力する際に、モデルプロパティの型に対して モデルプロパティとHiveデータ型とのマッピング 表で定義されている標準マッピング以外のHiveデータ型として取り扱う機能です。

モデルプロパティに対して、 モデルプロパティとHiveデータ型とのマッピング 表の「Hive (マッピング型変換)」に記載されているHiveデータ型に対するマッピングを行うことが可能です。

マッピング型変換を行うには、それぞれのモデルプロパティにマッピング型変換用の属性を指定します。属性によっては、さらにその属性が持つ各要素でデータ型の詳細情報を指定します。

マッピング型変換で利用可能な属性は以下の通りです。

マッピング型変換

属性

要素

型 5

内容

@directio.hive.string

-

DECIMAL

DATE

DATETIME

モデルプロパティをHiveの STRING 型にマッピング

@directio.hive.decimal

precision :精度(1 - 38)

scale :スケール(0 - 38)

DECIMAL

モデルプロパティを精度とスケールを持つHiveの DECIMAL 型にマッピング

@directio.hive.timestamp

-

DATE

モデルプロパティをHiveの TIMESTAMP 型にマッピング ( DATE からのマッピングでは時刻は常に 00:00:00 )

@directio.hive.char

length :最大文字列長(1 - 255)

TEXT

モデルプロパティをHiveの CHAR 型にマッピング

@directio.hive.varchar

length :最大文字列長(1 - 65535)

TEXT

モデルプロパティをHiveの VARCHAR 型にマッピング

5

この属性を指定することが可能なDMDLのプロパティの型です。

以下はマッピング変換機能の定義を付加したDMDLスクリプトの記述例です。

item = {
    @directio.hive.char(length = 2)
    item_no : TEXT;

    @directio.hive.decimal(precision = 20, scale = 4)
    unit_selling_price : DECIMAL;

    @directio.hive.string
    extended_price : DECIMAL;

    @directio.hive.timestamp
    order_date : DATE;

    @directio.hive.varchar(length = 1024)
    memo : TEXT;
};

Hiveデータ型とカラムナフォーマットのデータ型とのマッピング

Hiveデータ型とカラムナフォーマットのデータ型とのマッピングにおける制約ついては、Hiveの以下のカラムナフォーマットのドキュメントを参照してください。

LanguageManual ORC [https://cwiki.apache.org/confluence/display/Hive/LanguageManual+ORC]

Parquet [https://cwiki.apache.org/confluence/display/Hive/Parquet]

カラムナフォーマットファイルから除外するプロパティ

特定のプロパティをカラムナフォーマットファイルのカラムとして取り扱いたくない場合、プロパティに @directio.hive.ignore を指定します。

関連機能

Hive DDLの生成

アプリケーションの開発にGradleプロジェクトを利用している場合、Hive連携モジュールを利用するDMDLスクリプトからHiveのDDLを生成する generateHiveDDL タスクを利用することができます。

./gradlew generateHiveDDL

generateHiveDDL タスクを実行すると、プロジェクトの build/hive-ddl ディレクトリ配下にHiveのDDL文を含むSQLファイルが生成されます。

詳しくは、 Asakusa Gradle Plugin ユーザーガイド - Hive用DDLファイルの生成 を参照してください。

Direct I/O コマンドラインツールユーザーガイド

このドキュメントでは、Direct I/Oに関するコマンドラインツールの利用方法について紹介します。

ツールの配置と設定

Direct I/Oに関するコマンドラインツールは $ASAKUSA_HOME/directio/bin ディレクトリ内に格納されています。また、いずれのツールもAsakusa FrameworkのDirect I/Oに関する設定情報を利用します。これらの設定方法については Direct I/O ユーザーガイド を参照してください。

いずれのツールも hadoop コマンドを経由して実行するため、環境にHadoopがインストールされている必要があります。また、Hadoopのインストール先を通知するために、以下の環境変数のいずれかが必要です。

HADOOP_CMD

hadoop コマンドのパス

HADOOP_HOME

Hadoop のインストール先

PATH

hadoop コマンドが通っているパス

ツール固有の環境変数の設定

ここで説明するコマンドラインツールは、実行前に $ASAKUSA_HOME/directio/conf/env.sh を読み込んで必要な環境変数の設定などを行います。

以下は同ファイルの内容を改変し、環境変数 HADOOP_CMD を設定する例です。

export HADOOP_CMD=/usr/bin/hadoop

ファイル操作

ファイル操作を行うコマンドは、Direct I/Oのベースパスやファイルパターンを利用して、実際のデータソース内のファイルに対して処理を行います。

ファイルのリストアップ

$ASAKUSA_HOME/directio/bin/list-file.sh コマンドを利用すると、Direct I/Oのパスを使ってデータソース上のファイルやディレクトリ一覧をリストアップできます。

以下の形式で指定します。

list-file.sh <base-path> <resource-pattern> [<resource-pattern> [...]]

コマンドに指定可能な引数は以下のとおりです。

-h, -help

ヘルプメッセージを表示して終了します。

base-path

対象ファイルのベースパスを指定します。

ベースパスは利用するデータソースを検出するためのパスで、多くの場合にはデータソースを配置したパスを指定します。ここに指定するパスは、DSLの入出力定義において getBasePath() メソッドで定義したものを指定できます。

resource-pattern

対象ファイルのベースパスからの相対パスを指定します。

ここには * (ワイルドカード)などのメタ文字も指定できます。詳しくは ファイル名のパターン を参照してください。

Hint

パスにディレクトリを指定した場合に、ディレクトリの内容の表示が行われるわけではありません。ディレクトリの内容を表示したい場合、 <resource-pattern> の末尾に /* と指定してください。

利用例

ルートパス配下のすべてのディレクトリ/ファイルを出力する

list-file.sh / "**/*"

ベースパス result 配下の拡張子 .csv を持つファイルをサブディレクトリ含めてすべて出力する

list-file.sh result "**/*.csv"

ファイルの削除

$ASAKUSA_HOME/directio/bin/delete-file.sh コマンドを利用すると、Direct I/Oのパスを使ってデータソース上のファイルを削除できます。

以下の形式で指定します。

delete-file.sh [-r] <base-path> <resource-pattern> [<resource-pattern> [...]]

コマンドに指定可能な引数は以下のとおりです。

-h, -help

ヘルプメッセージを表示して終了します。

-r, -recursive

ファイルだけでなくディレクトリとその内容も削除します。

この指定がない場合、ディレクトリの削除は行いません。

base-path

対象ファイルのベースパスを指定します。

ベースパスは利用するデータソースを検出するためのパスで、多くの場合にはデータソースを配置したパスを指定します。ここに指定するパスは、DSLの入出力定義において getBasePath() メソッドで定義したものを指定できます。

resource-pattern

対象ファイルのベースパスからの相対パスを指定します。

ここには * (ワイルドカード)などのメタ文字も指定できます。詳しくは ファイル名のパターン を参照してください。

ファイル名のパターン

それぞれのコマンドの <resource-pattern> にはファイル名だけでなくワイルドカードなどのパターン用の文字列も利用できます。

ここに利用できるパターンは以下の通りです。

利用できるパターン

文字列

名前

概要

名前文字

リテラル

そのままファイル名として利用します。対象のデータソースが利用できるファイル名のうち、 / , \ , $ , * , ? , # , | , { , } , [ , ] 以外の文字を利用できます。

/

名前区切り

パスに含まれる名前の区切り文字です。

*

ワイルドカード

0個以上の任意の名前文字とマッチします。

{..|..|..}

選択

| で区切られたいずれかの名前にマッチします。 .. の部分には名前文字と名前区切りの組み合わせのみを指定できます。

上記のほかに、特別なディレクトリやファイル名として ** を利用できます。これは、検索対象以下のすべてのサブディレクトリ(自身のディレクトリも含む)とそれに含まれるファイルにマッチします。

ただし、 ** はディレクトリやファイル名の一部としては利用できません。たとえば、 **.csv というパターンは利用できず、代わりに **/*.csv と書きます。

Attention

利用しているシェルによっては、ファイル名のパターンに * 文字が含まれていた場合に自動的に展開されてしまいます。展開を回避するには、 "*" のようにダブルクウォート文字で囲むなどの指定を行なってください。

トランザクション操作

トランザクション操作を行うコマンドは、Direct I/Oを利用した際のトランザクション処理を直接制御できます。

トランザクション制御については Direct I/O ユーザーガイド を参照してください。

トランザクションのリストアップ

$ASAKUSA_HOME/directio/bin/list-transaction.sh コマンドを利用すると、Direct I/Oで実行中や実行に失敗したトランザクションの一覧を表示します。

以下の形式で指定します。

list-transaction.sh

コマンドには引数を指定せずに実行します。

このコマンドを実行すると、以下の情報を表示します。

表示されるトランザクションの情報

セクション

内容

Date

トランザクションを開始した日時

Execution ID

対象のジョブフローの実行ID

Status

トランザクションの状態

Comments

補助的な情報

コミットの適用

$ASAKUSA_HOME/directio/bin/apply-transaction.sh コマンドを利用すると、Direct I/Oでコミットに成功した未適用のトランザクションを、最後まで適用します。この操作によって、in-doubt状態になっているトランザクションを適切に終了させられます。

以下の形式で指定します。

apply-transaction.sh <execution-id>

コマンドに指定可能な引数は以下のとおりです。

execution-id

対象のジョブフローの実行ID

上記の実行IDを確認するには、 トランザクションのリストアップ を実行し、 Execution ID の項目を参照してください。また、同時に表示される Status の項目が Committed となっているもののみを、このコマンドで処理できます。 Status の項目が Committed でない場合、このコマンドを実行しても処理は行われません。

コミットの破棄

$ASAKUSA_HOME/directio/bin/abort-transaction.sh コマンドを利用すると、Direct I/Oで行われた任意のトランザクションを破棄できます。

以下の形式で指定します。

abort-transaction.sh <execution-id>

コマンドに指定可能な引数は以下のとおりです。

execution-id

対象のジョブフローの実行ID

上記の実行IDを確認するには、 トランザクションのリストアップ を実行し、 Execution ID の項目を参照してください。 Status の項が Committed , NOT Committed のいずれの場合でも途中結果を強制的に破棄します。

Warning

Status の項目が Committed になってるトランザクションに対してこのコマンドを実行すると、処理結果が中途半端にデータソース上に反映されたまま復元できなくなる場合があります。

そのようなトランザクションには通常 コミットの適用 を行うべきですが、コミットの内容が不要になった場合や、コミットの内容がエラーによりどうやっても適用できない場合などには、上記のコマンドも利用できます。

Hint

Status の項目が NOT Committed である場合、コミットの破棄はほぼロールバック操作と同様になります。ただし、Direct I/Oの出力時に「ステージ領域の省略」を行っていた場合には、途中結果が出力先に一部反映されている可能性があります。

Direct I/O CLI ユーザーガイド

この文書では、Direct I/O CLI ( directio コマンド ) の利用方法について説明します。

Experimental

Asakusa Framework バージョン 0.10.3 では、Direct I/O CLIは試験的機能として提供しています。

セットアップ

Direct I/O CLIは開発環境と運用環境の両方で利用することができます。

開発環境のセットアップ

開発環境では、開発環境用のAsakusa Frameworkがインストールされた状態であればDirect I/O CLIを利用することができます。開発環境上でAsakusa Frameworkをインストールする手順については、 Asakusa Framework スタートガイド や Asakusa Gradle Plugin ユーザーガイド などを参照してください。

運用環境のセットアップ

運用環境では、Asakusa Frameworkのデプロイメントアーカイブを配備した状態であればDirect I/O CLIを利用することができます。運用環境上でデプロイメントアーカイブを配置する手順については、 Asakusa Framework デプロイメントガイド などを参照してください。

directio コマンド

Direct I/O CLIの各機能は directio コマンドを通して利用します。セットアップが完了した環境であれば、 directio コマンドは $ASAKUSA_HOME/tools/bin 配下に配置されています。コマンドラインから directio コマンドを利用する場合、 $ASAKUSA_HOME/tools/bin 配下に環境変数 PATH を通しておくと便利です。

以降本書で directio コマンドを実行する例を示す際には、上記の PATH 環境変数が設定済であるものとします。

正しくセットアップが行われている環境でコマンドラインから directio コマンドを実行すると、以下のように表示されます。

$ directio
使用方法: directio <command> <command options>

利用可能なコマンドの一覧:
    configuration - Direct I/O の各種設定情報を表示する。
    copy - Direct I/O データソース上でリソースのコピーを行う。
    delete - Direct I/O のリソースを削除する。
    get - Direct I/O のリソースをローカルファイルシステム上にコピーする。
    list - Direct I/O のリソースを一覧表示する。
    mkdir - Direct I/O のデータソース上にディレクトリーを作成する。
    move - Direct I/O のデータソース上でリソースの移動を行う。
    put - ローカルファイルを Direct I/O のデータソースにコピーする。
    transaction - Direct I/O のトランザクションを操作する。

各コマンドの詳しい情報は 'directio <command> --help' を参照してください。

上記が表示されず、エラーメッセージが表示されてしまう場合には、セットアップ環境を確認してください。

Hadoop環境の設定

Direct I/O CLIを利用するにはHadoop環境がセットアップされている必要があります。

まず、 Asakusa on M3BPユーザーガイド - Hadoopとの連携 に示す手順などにより hadoop.embed true を指定してAsakusa Frameworkに組み込みのHadoopライブラリーを含めた場合、Direct I/O CLIはこれを使用します。

上記の設定を行わず、実行環境にインストール済みのHadoopと連携する場合、以下の環境変数のいずれかによって利用するHadoop環境を特定します。

HADOOP_CMD

hadoop コマンドのパス

HADOOP_HOME

Hadoopのインストール先

PATH

hadoop コマンドが通っているパス

上記の方法で利用可能なHadoopを解決できない場合、 directio コマンドは実行時にエラーとなります。

Asakusa Frameworkが利用するHadoop環境(Hadoopライブラリーや hadoop コマンドのパス)は、 asakusa コマンド 1 で確認することができます。

$ asakusa version -v
0.10.0
ASAKUSA_HOME: /home/asakusa/asakusa
Hadoop: /usr/local/lib/hadoop/bin/hadoop
java.version: 1.8.0_121
java.vendor: Oracle Corporation

asakusa version -v コマンドを実行した結果、 Hadoop: に表示されるHadoopライブラリーや hadoop コマンドをDirect I/O CLIは利用します。この値に N/A と表示される場合は利用可能なHadoopを解決できていない状態です。

1

asakusa コマンドについて詳しくは、 コマンドラインインターフェース - Asakusa CLI を参照してください。

コマンド体系

サブコマンド

directio コマンドはサブコマンドを指定することで様々な機能を呼び出します。サブコマンドには configuration や list 、 put といったものがあります。サブコマンドの中には、さらにサブコマンドを要求するものもあります。

コマンドラインから実行する際には、サブコマンド間をスペースで区切って指定します。

例えば、directio configuration list のように実行すると、環境上に設定されたDirect I/Oのデータソースをリストとして表示します。

$ directio configuration list
root

パラメータ

多くのサブコマンドでは、サブコマンドに続けて処理の対象を指定するパラメータを指定します。

コマンドラインから実行する際には、サブコマンドの後にパラメータをスペースで区切って指定します。

例えば、directio get は1つ目のパラメータに指定したDirect I/O上のパス上のファイルを、2つ目のオプションで指定したローカルパス上に保存します。

$ directio get result/category/result.csv /tmp

オプション

各サブコマンドにはサブコマンド共通、または固有のオプションが存在します。

コマンドラインから実行する際には、サブコマンドの後、またはパラメータ後にスペースで区切って指定します。多くのLinuxコマンドと同様に、いくつかのオプションでは -- から始まる記法の他、 - から始まる短縮記法を利用できます。

オプションによっては、オプション固有のパラメータを指定するものもあります。通常、オプションとそのパラメータはスペースで区切って指定しますが、一部のオプションでは -Akey=value のようにスペースで区切らずに指定することも可能です。

以下はサブコマンドの主なオプションです。サブコマンドによって使用できるオプションは異なるので、詳しくは各サブコマンドのヘルプを参照してください。

--conf, --configuration file

Direct I/O CLIが利用するDirect I/O設定ファイルのファイルパスを指定する。

既定値: $ASAKUSA_HOME/core/conf/asakusa-resources.xml

-s, --data-source

データソースIDを指定し、対応するデータソースに対する操作を行う

-e, --encoding encoding

コマンドの出力内容の文字セットエンコーディングを指定する。

デフォルトでは環境の標準エンコーディングを使用する。

-o, --output file

コマンドの出力内容を指定したファイルパスに保存する。デフォルトでは標準出力に出力する。

-v, --verbose

コマンド実行結果の出力に詳細な情報を含める。

-h, --help

ヘルプメッセージを表示する。サブコマンドが要求するオプションや追加のサブコマンドを確認する。

$ directio list --help
Usage: directio list [options] [directio-path..]
  Options:
    --conf, --configuration
      Hadoopの追加設定ファイルのパスを指定する。
      Default: /home/asakusa/asakusa/core/conf/asakusa-resources.xml
    -s, --data-source
      データソースIDを直接指定する（パスから推定したものを無視）。
    ...

コマンドリファレンス

directio コマンドのサブコマンド一覧を以下に示します。

directio サブコマンド

サブコマンド

カテゴリ

説明

directio list

ファイル操作

Direct I/Oのデータソースに含まれるファイルの一覧を表示する

directio mkdir

ファイル操作

Direct I/Oのデータソース上にディレクトリを作成する

directio get

ファイル操作

Direct I/Oのデータソース上のファイルをローカルファイルシステムにコピーする

directio put

ファイル操作

ローカルファイルシステム上のファイルをDirect I/Oのデータソース上にコピーする

directio delete

ファイル操作

Direct I/Oのデータソース上のファイルを削除する

directio copy

ファイル操作

Direct I/Oのデータソース間でファイルをコピーする

directio move

ファイル操作

Direct I/Oのデータソース間でファイルを移動する

directio configuration

設定

Direct I/Oの設定を表示する

directio transaction

トランザクション

Direct I/Oのトランザクション操作を行う

ファイル操作について

ここではファイル操作系のサブコマンドに共通するオプションや動作について説明します。

directio-path

コマンドのオプションに directio-path.. (ファイル名のパターン)を指定する場合、ここにはファイル名だけでなくワイルドカードなどのパターン用の文字列も利用できます。

ここに利用できるパターンは以下の通りです。

利用できるパターン

文字列

名前

概要

名前文字

リテラル

そのままファイル名として利用します。対象のデータソースが利用できるファイル名のうち、 / , \ , $ , * , ? , # , | , { , } , [ , ] 以外の文字を利用できます。

/

名前区切り

パスに含まれる名前の区切り文字です。

*

ワイルドカード

0個以上の任意の名前文字とマッチします。

{..|..|..}

選択

| で区切られたいずれかの名前にマッチします。 .. の部分には名前文字と名前区切りの組み合わせのみを指定できます。

上記のほかに、特別なディレクトリやファイル名として ** を利用できます。これは、検索対象以下のすべてのサブディレクトリ(自身のディレクトリも含む)とそれに含まれるファイルにマッチします。

ただし、 ** はディレクトリやファイル名の一部としては利用できません。たとえば、 **.csv というパターンは利用できず、代わりに **/*.csv と書きます。

Attention

利用しているシェルによっては、 directio-path に * 文字が含まれていた場合に自動的に展開されてしまいます。展開を回避するには、 "*" のようにダブルクウォート文字で囲むなどの指定を行なってください。

directio コマンドでは、上記の文法で指定したパスから、自動的にDirect I/Oのベースパスとリソースパターンを抽出します。

具体的には、パスの先頭から「名前区切り」ごとに「名前文字」のみで構成された部分をベースパスとして取り扱い、残りをリソースパターンとして取り扱います。なお、パスの末尾の名前は常にリソースパターンとして扱い、ベースパスが空になった場合には / として扱います。

以下は例です。

a/b/*.csv -> a/b + *.csv

a/b.csv -> a + b.csv

**/*.csv -> / + **/*.csv

このパスは、以下のコマンドで利用します。

directio list の引数

directio mkdir の引数

directio get の先頭の引数 (コピー元)

directio put の末尾の引数 (コピー先)

directio copy の引数

directio move の引数

Hint

Direct I/Oはベースパスの最長一致でデータソースを特定しています。上記とは異なる方法でデータソースを指定する場合、 --datasource オプションに対象のデータソースIDを指定してください。

ファイルの移動・コピーの動作

directio コマンドにおいて、下記のファイルの移動やコピーを行うコマンドは、移動・コピー先（宛先）に関する共通の動作があります。

directio get

directio put

directio copy

directio move

宛先にディレクトリが存在する場合、そのディレクトリ配下に移動・コピーを行う

複数のファイルやディレクトリを移動・コピー可能

宛先にファイルが存在する場合、そのファイルに上書き操作を行う

移動・コピー元は単一のファイルやディレクトリでなければならない

--overwrite オプションを指定する必要がある

宛先にファイルやディレクトリが 存在せず 、その親ディレクトリが存在する場合、宛先に単一のファイルを作成する

移動・コピー元は単一のファイルやディレクトリでなければならない

宛先にファイルやディレクトリが 存在せず 、その親ディレクトリも 存在しない 場合、エラーとなる

また、それぞれ下記の共通オプションを利用可能です。

-r, --recursive

ファイルだけでなく、ディレクトリーもコピーする。

このオプションを指定しない場合、ディレクトリーのコピーを行わずスキップする。

directio move においては常にディレクトリーの移動を行うため、このオプションは利用できない。

ディレクトリーを移動・コピーする際に宛先にすでにディレクトリーが存在する場合、コピー元のディレクトリーの内容を宛先にマージする。

-w, --overwrite

宛先にすでにファイルが存在した場合、そのファイルを上書きする。

このオプションを指定せずに、ファイルを上書きしようとした場合エラーとなる。

-p, --parallel

複数ファイルの操作を並列に実行する。

directio list

list はDirect I/Oのデータソースに含まれるファイルの一覧を表示します。

書式

directio list [options] [directio-path..]

使用例

list を標準のオプションで実行すると、Direct I/Oのすべてのデータソースに含まれるファイルやディレクトリーのパス一覧を表示します。

$ directio list
file:/home/asakusa/target/testing/directio/master
file:/home/asakusa/target/testing/directio/master/item_info.csv
file:/home/asakusa/target/testing/directio/master/store_info.csv
file:/home/asakusa/target/testing/directio/result
file:/home/asakusa/target/testing/directio/result/category
file:/home/asakusa/target/testing/directio/result/category/result.csv
file:/home/asakusa/target/testing/directio/result/error
file:/home/asakusa/target/testing/directio/result/error/2011-04-01.csv
file:/home/asakusa/target/testing/directio/sales
file:/home/asakusa/target/testing/directio/sales/2011-04-01.csv

list のオプションには表示するファイル名のパターンを指定することができます。

$ directio list "result/**/*"
file:/home/asakusa/target/testing/directio/result/category
file:/home/asakusa/target/testing/directio/result/category/result.csv
file:/home/asakusa/target/testing/directio/result/error
file:/home/asakusa/target/testing/directio/result/error/2011-04-01.csv

list を詳細オプション付きで実行すると、ファイルに付随する属性情報も表示します。

$ directio list -v "result/**/*"
total 4
file:/home/asakusa/target/testing/directio/result/category
    data source: root
      directory: true
file:/home/asakusa/target/testing/directio/result/category/result.csv
    data source: root
      directory: false
file:/home/asakusa/target/testing/directio/result/error
    data source: root
      directory: true
file:/home/asakusa/target/testing/directio/result/error/2011-04-01.csv
    data source: root
      directory: false

directio mkdir

mkdir はDirect I/Oのデータソース上にディレクトリを作成します。

書式

directio mkdir [options] directio-path..

使用例

$ directio mkdir /temp/foo

$ directio mkdir -v /temp/foo/bar
create directory: file:/home/asakusa/target/testing/directio/temp/foo/bar

directio get

get はDirect I/Oのデータソース上のファイルをローカルファイルシステムにコピーします。

書式

directio get [options] directio-path.. local-path

使用例

1つのファイルを取得する例です。

$ directio get /result/category/result.csv $HOME/work

ディレクトリ配下のすべてのファイルを取得する例です。 -r オプションを指定します。

$ directio get -r -v /result $HOME/work
copy directory: hdfs://<host>:8020/user/asakusa/target/testing/directio/result -> file:/home/asakusa/work/result
copy directory: hdfs://<host>:8020/user/asakusa/target/testing/directio/result/category -> file:/home/asakusa/work/result/category
copy file: hdfs://<host>:8020/user/asakusa/target/testing/directio/result/category/result.csv -> file:/home/asakusa/work/result/category/result.csv
copy directory: hdfs://<host>:8020/user/asakusa/target/testing/directio/result/error -> file:/home/asakusa/work/result/error
copy file: hdfs://<host>:8020/user/asakusa/target/testing/directio/result/error/2011-04-01.csv -> file:/home/asakusa/work/result/error/2011-04-01.csv

大量のファイルを取得する場合、 -p オプションを指定して並列にファイルを取得すると全体のファイル取得時間が短縮できる可能性があります。

$ directio get -r -p "/data/*" /mnt/data

directio put

put はローカルファイルシステム上のファイルをDirect I/Oのデータソース上にコピーします。

書式

directio put [options] local-path.. directio-path

使用例

1つのファイルをコピーする例です。 -w オプションを指定すると、すでに存在する同名のファイルを上書きします。

$ directio put -w example-dataset/sales/2011-04-01.csv /sales

ディレクトリ配下のすべてのファイルをコピーする例です。 -r オプションを指定します。

$ directio put -r -v $ASAKUSA_HOME/example-dataset/* /
copy directory: file:/home/asakusa/asakusa/example-dataset/master -> hdfs://<host>:8020/user/asakusa/target/testing/directio/master
copy file: file:/home/asakusa/asakusa/example-dataset/master/item_info.csv -> hdfs://<host>:8020/user/asakusa/target/testing/directio/master/item_info.csv
copy file: file:/home/asakusa/asakusa/example-dataset/master/store_info.csv -> hdfs://<host>:8020/user/asakusa/target/testing/directio/master/store_info.csv
copy directory: file:/home/asakusa/asakusa/example-dataset/sales -> hdfs://<host>:8020/user/asakusa/target/testing/directio/sales
copy file: file:/home/asakusa/asakusa/example-dataset/sales/2011-04-01.csv -> hdfs://<host>:8020/user/asakusa/target/testing/directio/sales/2011-04-01.csv

大量のファイルをコピーする場合、 -p オプションを指定して並列にファイルをコピーすると全体のファイル取得時間が短縮できる可能性があります。

$ directio put -r -p /mnt/data/* /data

directio delete

delete はDirect I/Oのデータソース上のファイルを削除します。

書式

directio delete [options] directio-path..

使用例

1つのファイルを削除する例です。

$ directio delete result/error/2011-04-01.csv

ディレクトリとその配下のすべてのファイルを削除する例です。 -r オプションを指定します。

$ directio delete -r -v result
delete: hdfs://<host>:8020/user/asakusa/target/testing/directio/result

データソース上のファイルをすべて削除する例です。

$ directio delete -r "/*"

Attention

先述の directio-path にも記載していますが、ファイル名にワイルドカードを含むパターンを指定する場合、利用するシェルによって意図せず展開されないよう "/*" のようにダブルクウォート文字で囲むなどの指定を行なってください。

directio copy

copy はDirect I/Oのデータソース間でファイルをコピーします。

書式

$ directio copy [options] source-directio-path.. destination-directio-path

使用例

1つのファイルをコピーする例です。

$ directio copy /result/category/result.csv /temp/result_bak.csv

ディレクトリとその配下のすべてのファイルをコピーする例です。 -r オプションを指定します。

$ directio copy -r -v /result /result_bak
copy directory: hdfs://<host>:8020/user/asakusa/target/testing/directio/result -> hdfs://<host>:8020/user/asakusa/target/testing/directio/result_bak
copy directory: hdfs://<host>:8020/user/asakusa/target/testing/directio/result/category -> hdfs://<host>:8020/user/asakusa/target/testing/directio/result_bak/category
copy file: hdfs://<host>:8020/user/asakusa/target/testing/directio/result/category/result.csv -> hdfs://<host>:8020/user/asakusa/target/testing/directio/result_bak/category/result.csv
copy directory: hdfs://<host>:8020/user/asakusa/target/testing/directio/result/error -> hdfs://<host>:8020/user/asakusa/target/testing/directio/result_bak/error
copy file: hdfs://<host>:8020/user/asakusa/target/testing/directio/result/error/2011-04-01.csv -> hdfs://<host>:8020/user/asakusa/target/testing/directio/result_bak/error/2011-04-01.csv

大量のファイルをコピーする場合、 -p オプションを指定して並列にファイルをコピーすると全体のファイル取得時間が短縮できる可能性があります。

$ directio put -r -p /data /work

directio move

move はDirect I/Oのデータソース間でファイルを移動します。

書式

$ directio move [options] source-directio-path.. destination-directio-path

使用例

1つのファイルを別ディレクトリに移動する例です。

$ directio move /result/category/result.csv /temp

ディレクトリとその配下のすべてのファイルを移動する例です。

$ directio move -v /result /result_bak
copy directory: hdfs://<host>:8020/user/asakusa/target/testing/directio/result -> hdfs://<host>:8020/user/asakusa/target/testing/directio/result_bak
copy directory: hdfs://<host>:8020/user/asakusa/target/testing/directio/result/category -> hdfs://<host>:8020/user/asakusa/target/testing/directio/result_bak/category
copy directory: hdfs://<host>:8020/user/asakusa/target/testing/directio/result/error -> hdfs://<host>:8020/user/asakusa/target/testing/directio/result_bak/error
copy file: hdfs://<host>:8020/user/asakusa/target/testing/directio/result/error/2011-04-01.csv -> hdfs://<host>:8020/user/asakusa/target/testing/directio/result_bak/error/2011-04-01.csv

directio configuration

configuration は、環境上のDirect I/Oの設定に関する情報を表示します。 configuration のサブコマンド一覧を以下に示します。

configuration サブコマンド

サブコマンド

説明

directio configuration list

データソースの一覧を表示する

directio configuration system

システム設定の一覧を表示する。

directio configuration list

list は環境上のDirect I/Oに定義されているデータソースの一覧を表示します。

書式

directio configuration list [options] [data-source-ID]

使用例

list を標準のオプションで実行すると、Direct I/OのデータソースID一覧を表示します。

$ directio configuration list
root
s3

list を詳細オプション付きで実行すると、各データソースの設定情報 2 も表示します。

$ directio configuration list -v
total 2
root
    ID: root
    base-path: /
    class: com.asakusafw.runtime.directio.hadoop.HadoopDataSource
    attributes:
    - fs.path: target/testing/directio
s3
    ID: s3
    base-path: s3/spool
    class: com.asakusafw.runtime.directio.hadoop.HadoopDataSource
    attributes:
    - fs.path: s3://example/var/spool
    - output.staging: false

2

Direct I/Oのデータソース設定については、 Direct I/O ユーザーガイド - データソースの設定 を参照してください。

directio configuration system

system は環境上のDirect I/Oのシステム設定 3 に関する情報を表示します。

書式

directio configuration system [options]

使用例

$ directio configuration system
configuration: /home/asakusa/asakusa/core/conf/asakusa-resources.xml
system directory: file:/home/asakusa/_directio
local temporary: N/A

3

Direct I/Oのシステム設定については、 Direct I/O ユーザーガイド - その他の設定 を参照してください。

directio transaction

transaction は、Direct I/Oのトランザクション操作 4 を行います。 transaction のサブコマンド一覧を以下に示します。

transaction サブコマンド

サブコマンド

説明

directio transaction list

Direct I/Oのトランザクションの一覧を表示する

directio transaction show

Direct I/Oのトランザクションの詳細情報を表示する

directio transaction apply

Direct I/Oでコミットに成功した未適用のトランザクションを適用する

directio transaction abort

Direct I/Oのトランザクションを破棄する

4

Direct I/Oのトランザクション制御については Direct I/O ユーザーガイド を参照してください。

directio transaction list

list はDirect I/Oのトランザクションの一覧を表示します。

書式

$ directio transaction list [options]

使用例

実行中のDirect I/Oトランザクションが存在しない場合は、以下のように表示されます。

$ directio transaction list
17/11/07 17:11:29 INFO hadoop.DirectIoTransactionEditor: Start listing Direct I/O transactions
17/11/07 17:11:29 INFO hadoop.DirectIoTransactionEditor: There are no Direct I/O transactions

実行中のDirect I/Oトランザクションが存在する場合は、以下のように表示されます。詳細オプション付きで実行すると、トランザクションに関する詳細な情報が表示されます。

$ directio transaction list -v
17/11/07 17:19:01 INFO hadoop.DirectIoTransactionEditor: Start listing Direct I/O transactions
17/11/07 17:19:02 INFO hadoop.DirectIoTransactionEditor: Start extracting 1 Direct I/O commit information
17/11/07 17:19:02 INFO hadoop.DirectIoTransactionEditor: Finish listing Direct I/O transactions
c09f4137-5d0b-4c9c-8bee-69eb05c13bc8
    ID: c09f4137-5d0b-4c9c-8bee-69eb05c13bc8
    status: Committed
    date: 2017-11-07T08:18:33Z
    comment:
    > User Name: asakusa
    > Batch ID: m3bp.perf.average.cogsort.once
    > Flow ID: cogsort_once
    > Execution ID: c09f4137-5d0b-4c9c-8bee-69eb05c13bc8
    > Batch Arguments: {input=10G/input, output=10G/output}

directio transaction show

show はDirect I/Oのトランザクションの詳細情報を表示します。

コマンドのパラメータには list で表示した実行IDを指定します。

書式

$ directio transaction show [options] execution-ID

使用例

$ directio transaction show c09f4137-5d0b-4c9c-8bee-69eb05c13bc8
ID: c09f4137-5d0b-4c9c-8bee-69eb05c13bc8
status: Committed
date: 2017-11-07T08:18:33Z
comment:
> User Name: asakusa
> Batch ID: m3bp.perf.average.cogsort.once
> Flow ID: cogsort_once
> Execution ID: c09f4137-5d0b-4c9c-8bee-69eb05c13bc8
> Batch Arguments: {input=10G/input, output=10G/output}

directio transaction apply

apply はDirect I/Oでコミットに成功した未適用のトランザクションを、最後まで適用します。この操作によって、in-doubt状態になっているトランザクションを適切に終了させることができます。

コマンドのパラメータには list で表示した実行IDを指定します。 list や show で表示される status の項目が Committed となっているもののみを、このコマンドで処理できます。 status の項目が Committed でない場合、このコマンドを実行するとエラーとなります。

書式

$ directio transaction apply [options] execution-ID

使用例

$ directio transaction apply -v 3819e025-4472-447f-9cf5-bd2df2507337
apply transaction
ID: 3819e025-4472-447f-9cf5-bd2df2507337
status: Committed
date: 2017-11-08T07:42:15Z
comment:
> User Name: asakusa
> Batch ID: m3bp.perf.average.cogsort.once
> Flow ID: cogsort_once
> Execution ID: 3819e025-4472-447f-9cf5-bd2df2507337
> Batch Arguments: {input=1G/input, output=1G/output}
17/11/08 16:46:28 INFO hadoop.DirectIoTransactionEditor: Start applying Direct I/O transaction (executionId=3819e025-4472-447f-9cf5-bd2df2507337)
17/11/08 16:46:28 INFO hadoop.DirectIoTransactionEditor: Start initializing Direct I/O data stores
17/11/08 16:46:28 INFO hadoop.DirectIoTransactionEditor: Finish initializing Direct I/O data stores
17/11/08 16:46:28 INFO hadoop.DirectIoTransactionEditor: Deleting commit mark (executionId=3819e025-4472-447f-9cf5-bd2df2507337, path=file:/home/asakusa/_directio/transactions/commit-3819e025-4472-447f-9cf5-bd2df2507337)
17/11/08 16:46:28 INFO hadoop.DirectIoTransactionEditor: Finish applying Direct I/O transaction (executionId=3819e025-4472-447f-9cf5-bd2df2507337)

directio transaction abort

abort はDirect I/Oで行われた任意のトランザクションを破棄します。

コマンドのパラメータには list で表示した実行IDを指定します。

status の項が Committed , Uncommitted のいずれの場合でも途中結果を強制的に破棄することができます。 status の項が Committed のトランザクションを破棄する場合、 --force ( -f ) オプションを指定します。

Warning

status の項目が Committed になってるトランザクションに対してこのコマンドを実行すると、処理結果が中途半端にデータソース上に反映されたまま復元できなくなる場合があります。

そのようなトランザクションには通常 apply によってコミットの適用を行うべきですが、コミットの内容が不要になった場合や、コミットの内容がエラーによりどうやっても適用できない場合などには、上記のコマンドも利用できます。

Hint

status の項目が Uncommitted である場合、コミットの破棄はほぼロールバック操作と同様になります。ただし、Direct I/Oの出力時に「ステージ領域の省略」を行っていた場合には、途中結果が出力先に一部反映されている可能性があります。

書式

$ directio transaction abort [options] execution-ID

使用例

$ directio transaction abort -v a1b4286f-b316-4cc4-b6e6-9c49a8b723a1
abort transaction
ID: a1b4286f-b316-4cc4-b6e6-9c49a8b723a1
status: Uncommitted
date: 2017-11-08T07:47:55Z
comment:
> User Name: asakusa
> Batch ID: m3bp.perf.average.cogsort.once
> Flow ID: cogsort_once
> Execution ID: a1b4286f-b316-4cc4-b6e6-9c49a8b723a1
> Batch Arguments: {input=1G/input, output=1G/output}
17/11/08 16:49:09 INFO hadoop.DirectIoTransactionEditor: Start aborting Direct I/O transaction (executionId=a1b4286f-b316-4cc4-b6e6-9c49a8b723a1)
17/11/08 16:49:09 INFO hadoop.DirectIoTransactionEditor: Start initializing Direct I/O data stores
17/11/08 16:49:09 INFO hadoop.DirectIoTransactionEditor: Finish initializing Direct I/O data stores
17/11/08 16:49:09 INFO hadoop.DirectIoTransactionEditor: Deleting transaction info (executionId=a1b4286f-b316-4cc4-b6e6-9c49a8b723a1, path=file:/home/asakusa/_directio/transactions/commit-a1b4286f-b316-4cc4-b6e6-9c49a8b723a1)
17/11/08 16:49:09 INFO hadoop.DirectIoTransactionEditor: Finish aborting Direct I/O transaction (executionId=a1b4286f-b316-4cc4-b6e6-9c49a8b723a1)

外部システムとの連携 - WindGate

WindGateはバッチに対するデータの外部入出力を行うモジュールです。

WindGateは「ポータブルなデータ転送ツール」して位置づけられ、以下の特徴を持ちます。

フラットファイルに対応

ローカルファイルシステム上のフラットファイル(CSV形式)に対するデータ入出力に対応しています。

様々なRDBMSに対応

DBMS固有の機能に依存せず、標準SQL/JDBCインターフェースのみを使用した実装を提供します。

様々な構成に対応

様々なクラスター構成やOS上で動作するように設計されています。

外部から拡張しやすい

データ入出力部分を拡張しやすいアーキテクチャを採用しています。

関連するドキュメント

WindGateスタートガイド

WindGateユーザーガイド

WindGateに関するログ一覧

WindGate開発者ガイド

WindGate TSV

WindGateスタートガイド

この文書では Asakusa Framework スタートガイド の構成で、WindGateを利用する方法について簡単に紹介します。

See also

WindGateのより詳しい情報は WindGateユーザーガイド を参照して下さい。

プロファイルの設定

WindGateは、外部システムとの入出力の定義を「プロファイル」として定義します。

プロファイルを定義したプロパティファイルは、 $ASAKUSA_HOME/windgate/profile 配下に <プロファイル名>.properties という名前で配置します。

標準ではプロファイル名 asakusa 用のプロファイル定義ファイルとして asakusa.properties が配置されています。プロファイルの定義情報は環境に合わせて変更してください。

このガイドでの構成

このガイドでは、次のような前提でアプリケーションを作成します。

組み込みのHadoopライブラリーを使用する

入出力データとしてCSVファイルを利用し、これを開発環境上(ローカル)に配置する

実行環境にインストールされているHadoopを利用する場合や、CSVファイルでなくデータベースを利用したい場合などでは、 WindGateユーザーガイド を参考に設定を行ってください。

Hadoopの設定

WindGateを利用したバッチアプリケーションを実行するにはHadoopの実行環境が必要です。実行環境にHadoopが用意されていない場合、Asakusa FrameworkのデプロイメントアーカイブにHadoopライブラリーを組み込むことでも、WindGateを実行することができます。

デプロイメントアーカイブにHadoopライブラリーを組み込むには、プロジェクトのビルドスクリプト build.gradle の末尾に以下の設定を追加します。

build.gradle

asakusafwOrganizer {
    profiles.prod {
        hadoop.embed true
    }
}

ベースディレクトリの設定

CSVファイルを格納するディレクトリは、プロファイル上で設定します。

$ASAKUSA_HOME/windgate/profile/asakusa.properties (プロファイル asakusa 用の構成) のファイルをエディタで開き、 resource.local.basePath の内容にディレクトリへのフルパスを指定します。

なお、初期状態ではここに /tmp/windgate-${USER} が指定されています 1 。このドキュメントでは、この値を変更せず、初期設定のままにしたという前提で進めます。

1

${環境変数名} という形式で環境変数を指定できます。初期状態では、 /tmp/windgate-<ログインユーザー名> をベースディレクトリとして利用しています。

データモデルクラスの生成

WindGateではモデルをDMDLで記述します。 DMDLの記述方法については「 DMDLスタートガイド 」などを参考にしてください。

DMDLスクリプトはプロジェクトの src/main/dmdl ディレクトリ以下に配置し、スクリプトのファイル名には .dmdl の拡張子を付けて保存します。

データモデルクラスを作成するには、データモデルの定義情報を記述後にGradleの compileDMDL タスクを実行します。

CSV入出力への対応

データモデルの定義情報を作成したら、CSVの入出力に対応させたいデータモデルに対して、 @windgate.csv という属性を指定します。この属性が指定されたデータモデルは、宣言されたプロパティと同じ順序のフィールドを持つCSVファイルの入出力に対応します。

この属性は、データモデルの宣言の直前に指定します。以下は記述例です。

@windgate.csv
example_model = {
    // ... プロパティの定義
};

この状態でデータモデルを作成すると、データモデルのほかに以下の3つのクラスが作成されます。

<パッケージ名>.csv.<データモデル名>CsvSupport

<パッケージ名>.csv.Abstract<データモデル名>ImporterDescription

<パッケージ名>.csv.Abstract<データモデル名>ExporterDescription

より細かな設定については WindGateユーザーガイド を参照してください。

Asakusa DSLの記述

WindGateを利用する場合でも、Asakusa DSLの基本的な記述方法は同様です。 WindGate特有の部分は、以降で説明する CSVファイルをインポートする と CSVファイルをエクスポートする 部分のみです。

それ以外の部分については、 Asakusa DSLスタートガイド を参照してください。

CSVファイルをインポートする

開発環境のCSVファイルをインポートしてHadoopの処理を行う場合、 CSV入出力への対応 で生成した <パッケージ名>.csv.Abstract<データモデル名>ImporterDescription クラスのサブクラスを作成して必要な情報を記述します。

このクラスでは、下記のメソッドをオーバーライドします。

String getProfileName()

インポータが使用するプロファイル名を戻り値に指定します。

インポータは実行時に $ASAKUSA_HOME/windgate/profile 以下の <プロファイル名>.properties に記述された設定を元に動作します。今回はデフォルトを利用するので、 "asakusa" という文字列を return 文に指定してください。

String getPath()

インポートするCSVファイルのパスを指定します。

ここでは ベースディレクトリの設定 で指定した resource.local.basePath からの相対パスで指定します。ベースディレクトリの設定と合わせて /tmp/windgate-<ログインユーザー名>/<指定したパス> というファイルを利用します。

以下は Document というデータモデルを宣言した場合の実装例です。

public class DocumentFromCsv extends AbstractDocumentCsvImporterDescription {

    @Override
    public String getProfileName() {
        return "asakusa";
    }

    @Override
    public String getPath() {
        return "input.csv";
    }
}

ここで記述した内容は、ジョブフローの入力に対して、 @Import を利用して指定します。

CSVファイルをエクスポートする

ジョブフローの処理結果をCSVファイルにエクスポートする場合、 CSV入出力への対応 で生成した <パッケージ名>.csv.Abstract<データモデル名>ExporterDescription クラスのサブクラスを作成して必要な情報を記述します。

このクラスでは、下記のメソッドをオーバーライドします。

String getProfileName()

エクスポータが使用するプロファイル名を戻り値に指定します。

インポータと同様に "asakusa" という文字列を return 文に指定してください。

String getPath()

エクスポートするCSVファイルのパスを指定します。

インポータと同様に ベースディレクトリの設定 で指定した resource.local.basePath からの相対パスで指定します。ベースディレクトリの設定と合わせて /tmp/windgate-<ログインユーザー名>/<指定したパス> というファイルに結果を出力します。

なお、出力先にすでにファイルが存在する場合、エクスポート時に上書きされます。インポートに指定したファイルや、他のエクスポート処理で使用するファイルとは別のファイルを指定するようにしてください。

以下は Document というデータモデルを宣言した場合の実装例です。

public class DocumentToCsv extends AbstractDocumentCsvExporterDescription {

    @Override
    public String getProfileName() {
        return "asakusa";
    }

    @Override
    public String getPath() {
        return "output.csv";
    }
}

ここで記述した内容は、ジョブフローの入力に対して、 @Export を利用して指定します。

アプリケーションの実行

アプリケーションのビルドや実行方法は、通常のAsakusa Frameworkのアプリケーション開発と同様です。

CSVファイルをインポートする で指定したように、入力データのCSVファイルは /tmp/windgate-<ログインユーザー名>/input.csv など、 getPath() で指定したものを利用してください。

出力結果は同様に、 CSVファイルをエクスポートする で指定したように、 /tmp/windgate-<ログインユーザー名>/output.csv など、 getPath() で指定したパスに出力されているはずです。

アプリケーションの実行手順については、 Asakusa Framework スタートガイド などを参照してください。

WindGateユーザーガイド

この文書では、WindGateの利用方法について紹介します。

WindGateプロファイル

WindGateは「Hadoopクラスターとデータベース」または「Hadoopクラスターとローカルファイルシステム」などの二点間で様々なデータをやり取りするツールです。主に、Asakusa Frameworkでバッチアプリケーションを作成する際に、データフローの入力データや出力データを取り扱うために利用します。

WindGateでは、「Hadoopクラスター」や「データベース」、「ローカルファイルシステム」などのそれぞれを「リソース」という考え方で同じように取り扱います。 WindGateの「プロファイル」にそれぞれのリソースとアクセス方法を記述することで、リソース間で自由にデータをやり取りできるようにします。

また、このプロファイルはWindGateに複数登録することもでき、複数のデータベースやローカルファイルシステム上のパス、またはアクセスするHadoopクラスターへの通信方法など、複数の組み合わせを個別に管理できます。

WindGateのプロファイルは、 $ASAKUSA_HOME/windgate/profile/<プロファイル名>.properties (以降、構成ファイル)内に記述します。 <プロファイル名> の部分には、特定のプロファイルごとに名前を付けてその名前を指定します。

それぞれの構成ファイルには、Javaの一般的なプロパティファイルの文法で、主に下記のセクションを記述します。

プロパティファイルの項目

セクション名

内容

core

WindGate本体の設定

session

セッションの設定

process.basic

プロセスの設定

resource.hadoop

Hadoopクラスターの設定

resource.local

ローカルファイルシステムの設定

resource.jdbc

データベースの設定

ここでの「セクション」とは、該当するセクション名またはそのサブセクションとなるプロパティの項目のことをいいます。たとえば、構成ファイル内の core , core.maxProcesses などはいずれも core セクション内の要素です。

環境変数の利用

WindGateプロファイルのいくつかの項目では、項目値の文字列に ${変数名} という形式を指定することで、WindGateを起動した環境の環境変数を含められます。

また、 ${変数名-デフォルト値} のように、 変数名の後に - を指定して、その後にデフォルト値を記述することで、 WindGateを起動した環境の環境変数が存在しない場合に、ここで指定したデフォルト値を設定することができます。

WindGate本体の設定

WindGate本体の設定は、構成ファイル内の core セクション内に記述します。

同時に実行するデータ転送の設定

WindGateは、一度の処理で複数のリソース間でのデータ転送を行います。それぞれのデータ転送を同時に実行するには、次の設定を追加します。

同時に実行するデータ転送の設定

名前

値

core.maxProcesses

同時に実行可能なデータ転送数の最大

Attention

この設定はプロファイルごとに個別のものです。ここで同時実行数を1に設定しても、複数のプロファイルに対する処理を同時に行った場合、データ転送は二つ以上が同時に実行する場合があります。

Hint

この設定は、主にデータベースを利用するリソースなどでコネクション数に制限がある場合などを想定しています。特に制限がない場合には、WindGateを実行するコンピューターのコア数などと同じ数値にするのが良いでしょう。

セッションの設定

WindGateと連携したバッチアプリケーションを作成する場合、通常はそれぞれのジョブフローの入力と出力時にそれぞれWindGateの処理が実行されます。たとえば、ジョブフローの処理の開始時にWindGateを利用して、データベースの内容をHadoopクラスター上に展開し（インポート）、処理の終了時に計算結果をデータベースに書き戻します（エクスポート）。

それぞれのジョブフローは、一連のトランザクション処理とみなされているため、このWindGateを利用したインポートとエクスポートは一連の処理として関連付けられていなければなりません。この、処理を関連付けるための仕組みを「セッション」と呼びます。

WindGateのセッションはジョブフローの先頭でインポートを行う際に作成され、エクスポートが完了した後に破棄されます。セッションの作成から破棄までの間にジョブフローが失敗した場合、このセッションの情報を元に何らかの復旧作業を行います。

また、同じセッションが同時に複数作成されようとした場合、WindGateを間違えて多重に起動してしまっている可能性があります。このような間違いを防ぐためにも、セッションは利用されます。

セッションの設定は、構成ファイル内の session セクション内に記述します。

Note

現在のところ、WindGateには ローカルファイルシステムを利用したセッション のみが提供されています。

ローカルファイルシステムを利用したセッション

セッション情報をローカルファイルシステム上に保持するには、 session セクションに下記の内容を指定します。

ローカルファイルシステムを利用したセッションの設定

名前

値

session

com.asakusafw.windgate.file.session.FileSessionProvider

session.directory

セッション情報を保持させるディレクトリ

ここで、 session.directory で指定したディレクトリ以下にセッションの情報に関するファイルが作成されます。このプロパティには、 ${環境変数名} の形式で環境変数を利用できます。特に、 ${WINDGATE_PROFILE} という値に利用中のプロファイル名が格納されているので、その値を利用するとプロファイルごとにディレクトリを分けられて便利です。

Attention

複数のプロファイルを利用する場合、かならずそれぞれのプロファイルで利用するディレクトリを分けてください。同じディレクトリにした場合、それぞれのプロファイルを参照するWindGateを同時に実行した際に、正しく動作しない可能性があります。

Note

この機能は、OSのファイルロックを利用して実現しています。ファイルロックが正しく動作しないOSやファイルシステム上では予想外の動作をするかもしれません。

プロセスの設定

WindGateは二つのリソースの間でデータを転送するツールです。この転送時に二つのリソースを仲立ちするのが「プロセス」で、入力元からデータを取り出して、出力先にそのデータを書き出す処理を行います。

また、WindGateは一度の処理内で、複数のリソース間のデータ転送を行います。入力と出力の対になるリソース間ごとにプロセスが作成され、同時に実行するプロセスの個数は 同時に実行するデータ転送の設定 で指定できます。

プロセスの設定は、構成ファイル内の process.basic セクション内に記述します。

Note

ここでのセクション名が process.basic となっているのは、このプロセスが「通常の方法でデータ転送を行う」という役割を持っているためです。将来、キャッシュの機能などがサポートされる際には、 process セクションも増える予定です。

Note

ここでの「プロセス」はUNIXのプロセスとは別物です。実際、WindGateのプロセスは、同一JavaVM上のそれぞれのスレッドで実行されます。

通常のデータ転送プロセス

標準的なデータ転送プロセスを利用するには、 process.basic セクションに以下のように記述します。

通常のデータ転送プロセスの設定

名前

値

process.basic

com.asakusafw.windgate.core.process.BasicProcessProvider

この項目には、特に追加の設定はありません。

再試行可能なデータ転送プロセス

再試行可能なデータ転送プロセスを利用するには、 process.basic セクションに以下のように記述します。

再試行可能なデータ転送プロセスの設定

名前

値

process.basic

com.asakusafw.windgate.retryable.RetryableProcessProvider

process.basic.component

com.asakusafw.windgate.core.process.BasicProcessProvider

process.basic.retryCount

リトライ回数

process.basic.retryInterval

再試行までの待機時間 (秒)

process.basic.component は実際に利用するデータ転送プロセスを設定します。現在利用可能なプロセスは 通常のデータ転送プロセス のみであるため、ここには com.asakusafw.windgate.core.process.BasicProcessProvider を指定します。

再試行可能なデータ転送プロセスでは、 process.basic.component に指定したデータ転送プロセスを利用し、通常の方法でデータ転送を行います。

データ転送に失敗した場合、 process.basic.retryCount に設定された回数を上限として、成功するまで上記プロセスを再実行します。また、 process.basic.retryInterval が指定されている場合、その時間だけ待機後にプロセスが再実行されます。 process.basic.retryInterval が指定されていない場合は即座に再実行します。

なお、このプロセスを利用するには、プラグインライブラリに asakusa-windgate-retryable の追加が必要です。詳しくは プラグインライブラリの管理 を参照してください。

Hadoopクラスターの設定

Asakusa Frameworkで作成したバッチからWindGateを利用する場合、リソースの片方にはHadoopクラスターを利用します。

Hadoopクラスターとの通信方法は、構成ファイル内の resource.hadoop セクション内に記述します。

同一環境上のHadoopを利用する

WindGateを起動したコンピュータ上のHadoopを利用するには、 resource.hadoop セクションに以下のように記述します。

同一環境上のHadoopを利用する設定

名前

値

resource.hadoop

com.asakusafw.windgate.hadoopfs.HadoopFsProvider

resource.hadoop.basePath

転送先のベースパス (省略可)

resource.hadoop.basePath は転送先のベースパスで、省略時はHadoopのデフォルト設定を利用します。 URI形式で、 hdfs://<host>:8080/user/asakusa 等のHadoopファイルシステム上のパスを指定できます。

上記の設定のうち、先頭の resource.hadoop を除くすべての項目の値の中に ${環境変数名} という形式で環境変数を含められます。

なお、このリソースを利用するには、プラグインライブラリに asakusa-windgate-hadoopfs の追加が必要です。詳しくは プラグインライブラリの管理 を参照してください。

Attention

Asakusa Framework 0.7.0 より、設定 resource.hadoop.compression は利用できなくなりました。転送時の圧縮はフレームワークが規定する内部の形式を利用するようになります。

Hint

通常の利用方法では、 resource.hadoop.basePath を設定する必要はありません。既定値以外のファイルシステムを利用する場合などに利用することを想定しています。

Hadoopを利用する際の環境変数

Hadoopクラスターと通信するリソースを利用するには、WindGateの起動時にHadoopの設定がすべて利用可能である必要があります。 WindGate起動時のHadoopの設定と、バッチで利用するHadoopの設定が異なる場合、正しく動作しない可能性があります。

環境変数の設定方法は WindGateの環境変数設定 を参照してください。

SSH経由でリモートのHadoopを利用する

WindGateからリモートコンピュータにSSHで接続し、そこにインストールされたHadoopを利用するには、 resource.hadoop セクションに以下のように記述します。また、 Hadoopブリッジ をリモートコンピュータ上にインストールしておく必要があります。

SSH経由でリモートのHadoopを利用する設定

名前

値

resource.hadoop

com.asakusafw.windgate.hadoopfs.jsch.JschHadoopFsProvider

resource.hadoop.user

ログイン先のユーザー名

resource.hadoop.host

SSHのリモートホスト名

resource.hadoop.port

SSHのリモートポート番号

resource.hadoop.privateKey

ローカルの秘密鍵の位置

resource.hadoop.passPhrase

秘密鍵のパスフレーズ

resource.hadoop.env.ASAKUSA_HOME

ログイン先の Asakusa Framework のインストール先

resource.hadoop.env.<name>

ログイン先の環境変数 <name> の値

上記の設定のうち、先頭の resource.hadoop を除くすべての項目の値の中に ${環境変数名} という形式で環境変数を含められます。

なお、このリソースを利用するには、プラグインライブラリに asakusa-windgate-hadoopfs 、および $ASAKUSA_HOME/windgate/lib ディレクトリに JSch 1 の追加が必要です。詳しくは プラグインライブラリの管理 を参照してください。

リモートと通信する際に、SSHで接続する元でもHadoopの設定が必要です。必要な環境変数については Hadoopを利用する際の環境変数 を参照してください。

Attention

Asakusa Framework 0.7.0 より、設定 resource.hadoop.compression は利用できなくなりました。転送時の圧縮はフレームワークが規定する内部の形式を利用するようになります。

1

http://www.jcraft.com/jsch/

Hadoopブリッジ

WindGateからSSHを経由してHadoopにアクセスする際に、HadoopブリッジとよぶAsakusa Frameworkのツールを経由します。

このツールは通常 $ASAKUSA_HOME/windgate-ssh というディレクトリにインストールされていて、リモートコンピューターのAsakusa Frameworkにも同様のディレクトリが必要です。また、プロファイルの resource.hadoop.env.ASAKUSA_HOME には、リモートコンピューターのAsakusa Frameworkのインストール先をフルパスで指定してください。

このツールの内部では、以下の順序でリモートコンピューターの hadoop コマンドを検索し、そのコマンドでHadoopクラスターの操作を行います。

リモートコンピューターのAsakusa Frameworkに組み込みのHadoop 2 がインストールされている場合、そのHadoop環境を利用します。

環境変数 HADOOP_CMD が設定されている場合、 $HADOOP_CMD を hadoop コマンドとみなして利用します。

環境変数 HADOOP_HOME が設定されている場合、 $HADOOP_HOME/bin/hadoop コマンドを利用します。

hadoop コマンドのパスが通っている場合、それを利用します。

上記のうち、必要な環境変数をプロファイル内の resource.hadoop.env.<name> や、リモート環境上の $ASAKUSA_HOME/windgate-ssh/conf/env.sh ファイル内で設定してください。結果としてコマンドが見つからなかった場合にはエラーになります。

また、ログの設定は $ASAKUSA_HOME/windgate-ssh/conf/logback.xml で行えます。 WindGate本体と同様に、SLF4JとLogbackを利用しています 3 。

Attention

HadoopブリッジはSSH経由で実行され、標準入出力を利用してWindGateとデータのやり取りを行います。ブリッジのJavaプログラム内で標準出力を利用しようとした場合、標準エラー出力にリダイレクトされるようになっています。そのため、ログの設定を行う際には、ログメッセージの出力先に注意してください。通常はログ出力先に標準出力を設定しないようにしてください。

また、 $ASAKUSA_HOME/windgate-ssh/conf/env.sh に指定した HADOOP_USER_CLASSPATH_FIRST の設定は、ログの設定を有効にするためにも必要です。特別な理由でHadoopのクラスパスを優先したい時を除き、 HADOOP_USER_CLASSPATH_FIRST の設定を変更しないようにしてください。

2

組み込みのHadoopについては、 WindGateスタートガイド - Hadoopの設定 を参照してください。

3

WindGateのログ設定 を参照

ローカルファイルシステムの設定

WindGateのリソースとして、WindGateを起動したコンピュータのファイルシステムを指定できます 4 。

構成ファイル内の resource.local セクション内に以下の設定を記述します。

ローカルファイルシステムを利用する設定

名前

値

resource.local

com.asakusafw.windgate.stream.file.FileResourceProvider

resource.local.basePath

ベースパス

resource.local.basePath は絶対パスで指定し、WindGateはそのパス以下のみを利用します。また、 resource.local.basePath には ${環境変数名} の形式で環境変数を指定できます。

上記の設定のうち、先頭の resource.local を除くすべての項目の値の中に ${環境変数名} という形式で環境変数を含められます。

なお、このリソースを利用するには、プラグインライブラリに asakusa-windgate-stream の追加が必要です。詳しくは プラグインライブラリの管理 を参照してください。

Warning

開発環境では、ベースパスに壊れてもよいディレクトリを指定してください。ここで指定したパスはテスト実行時などにテストドライバーが削除したり変更したりします。

4

WindGateを起動したコンピュータから、OSのファイルシステムを利用するというだけですので、ネットワークファイルシステム等でもファイルシステム上にマウントしてあれば利用可能です。なお、「ローカル」と書いているのは、Hadoopのファイルシステムと区別するためです。

データベースの設定

WindGateのリソースとして、JDBCをサポートするデータベースを指定できます。

現在の構成では、WindGateから直接JDBCドライバーを利用して対象のデータベースにアクセスします。また、データの取得にはテーブルを SELECT 文で取得し、データの書き戻しにはテーブルを TRUNCATE した後にバッチモードで INSERT 文を発行します。

Warning

この構成では、データの書き出し前に対象のテーブルの内容を完全に削除します。そのため、書き出し先のテーブルには通常利用するテーブルとは別のテーブルを指定し、WindGateの外側でマージ処理等を行ってください。

Attention

この構成では、データの取得時にアプリケーション側でのページネーション等を行いません。そのため、MySQLなどのカーソル機能が十分でないデータベースでは、巨大なデータを取得する際に十分なパフォーマンスが得られません。特に、MySQLの場合には設定に resource.jdbc.batchGetUnit=1000 , resource.jdbc.properties.useCursorFetch=true 等を指定し、カーソルを利用するようにしてください。

構成ファイル内の resource.jdbc セクション内に以下の設定を記述します。

データベースを利用する設定

名前

値

resource.jdbc

com.asakusafw.windgate.jdbc.JdbcResourceProvider

resource.jdbc.driver

JDBCドライバーのクラス名

resource.jdbc.url

接続先データベースのJDBC URL

resource.jdbc.user

データベースのユーザー名

resource.jdbc.password

データベースのパスワード

resource.jdbc.batchGetUnit

一度に取得するデータの件数 (読み出し時) 5

resource.jdbc.batchPutUnit

一度に挿入するデータの件数 (書き込み時) 6

resource.jdbc.connect.retryCount

接続時のリトライ回数 (省略時にはリトライなし)

resource.jdbc.connect.retryInterval

接続リトライまでの間隔 (秒、省略時には10秒)

resource.jdbc.statement.truncate

テーブルの内容を削除する際の文形式 7 (省略時には TRUNCATE 文)

resource.jdbc.properties.<キー名>

コネクションプロパティの値

resource.jdbc.optimizations

データベースとの接続時に利用する最適化オプション

上記の設定のうち、先頭の resource.jdbc を除くすべての項目の値の中に ${環境変数名} という形式で環境変数を含められます。

なお、このリソースを利用するには、プラグインライブラリに asakusa-windgate-jdbc とJDBCドライバーライブラリの追加が必要です。詳しくは プラグインライブラリの管理 を参照してください。

5

この値は Statement.setFetchSize() に設定します。 PostgreSQL等ではこの設定によってカーソルを利用するモードになります。この値が未設定の場合や 0 を設定した場合、 Statement.getFetchSize() は既定値が利用されます。

6

大きすぎる値を指定するとメモリ不足で正しく動作しません。 1000から10000程度での動作を確認しています。

7

この設定は java.text.MessageFormat の形式で指定し、削除対象のテーブル名は {0} で指定してください。省略時には TRUNCATE TABLE {0} が利用され、代わりに DELETE FROM {0} などを指定できます。なお、 MessageFormat ではシングルクウォート ( ' ) が特殊文字として取り扱われることに注意が必要です。

データベース接続時の最適化オプション

resource.jdbc.optimizations にはWindGateで利用可能なデータベース固有の最適化オプションを指定します。

本バージョンでは、以下のオプションが利用可能です。

データベース接続時の最適化オプション

オプション

内容

ORACLE_DIRPATH

Oracleのダイレクト・パス・インサートを有効にする。実行するINSERT文に対して、APPEND_VALUESヒントを指定する。

WindGateの実行環境でダイレクト・パス・インサートを利用にするには、このオプション指定に加えて、 データベースを利用するエクスポーター記述 でオプションを指定する必要がある。

その他のWindGateの設定

WindGateプロファイルのほかに、WindGate全体の設定に関するものがいくつか用意されています。

WindGateの環境変数設定

WindGateの実行に特別な環境変数を利用する場合、 $ASAKUSA_HOME/windgate/conf/env.sh 内でエクスポートして定義できます。

WindGateをAsakusa Frameworkのバッチから利用する場合、以下の環境変数が必要です。

WindGateの実行に必要な環境変数

名前

備考

ASAKUSA_HOME

Asakusaのインストール先パス。

HADOOP_USER_CLASSPATH_FIRST

WindGateのログ設定 時にHadoopのログ機構を利用しないための設定。 true を指定する。

特別な理由がない限り、 ASAKUSA_HOME はWindGateを実行する前にあらかじめ定義しておいてください。 $ASAKUSA_HOME/windgate/conf/env.sh では、その他必要な環境変数を定義するようにしてください。

Hint

YAESS を経由してWindGateを実行する場合、WindGateで利用する環境変数 ASAKUSA_HOME はYAESS側の設定で行えます。詳しくは YAESSユーザーガイド を参照してください。

その他、以下の環境変数を利用可能です。

WindGateで利用可能な環境変数

名前

備考

HADOOP_CMD

利用する hadoop コマンドのパス。

HADOOP_HOME

Hadoopのインストール先パス。

WINDGATE_OPTS

WindGateを実行するJava VMの追加オプション。

なお、WindGateの本体は、以下の規約に従って起動します (上にあるものほど優先度が高いです)。

Asakusa Frameworkに組み込みのHadoop 8 がインストールされている場合、そのHadoopライブラリーを利用します。

環境変数に HADOOP_CMD が設定されている場合、 $HADOOP_CMD コマンドを経由して起動します。

環境変数に HADOOP_HOME が設定されている場合、 $HADOOP_HOME/bin/hadoop コマンドを経由して起動します。

hadoop コマンドのパスが通っている場合、 hadoop コマンドを経由して起動します。

このため、 HADOOP_CMD と HADOOP_HOME の両方を指定した場合、 HADOOP_CMD の設定を優先します。

Attention

Asakusa Framework バージョン 0.9系以前では hadoop コマンドが見つからない場合、WindGateは代わりに java コマンドを利用してアプリケーションを起動する機能が含まれていましたが、バージョン 0.10 よりこの機能は廃止されました。

8

組み込みのHadoopについては、 WindGateスタートガイド - Hadoopの設定 を参照してください。

WindGateのログ設定

WindGateは内部のログ表示に SLF4J 9 、およびバックエンドに Logback 10 を利用しています。ログの設定を変更するには、 $ASAKUSA_HOME/windgate/conf/logback.xml を編集してください。

また、WindGateの実行時には以下の値がシステムプロパティとして設定されます。

WindGate実行時のシステムプロパティ

名前

値

com.asakusafw.windgate.log.batchId

バッチID

com.asakusafw.windgate.log.flowId

フローID

com.asakusafw.windgate.log.executionId

実行ID

Logback以外のログの仕組みを利用する場合、 $ASAKUSA_HOME/windgate/lib にあるLogback関連のライブラリを置換した上で、設定ファイルを $ASAKUSA_HOME/windgate/conf 以下に配置します (ここは実行時にクラスパスとして設定されます)。

9

http://www.slf4j.org/

10

http://logback.qos.ch/

プラグインライブラリの管理

WindGateの様々な機能は、プラグイン機構を利用して実現しています。それぞれのプラグイン、およびプラグインが利用する依存ライブラリは、 $ASAKUSA_HOME/windgate/plugin ディレクトリ直下に配置してください。

たとえば、WindGateはHadoopクラスターにアクセスする際にもプラグインが必要です。標準的なものはWindGate導入時に自動的にプラグインが追加されますが、その他のプラグインは拡張モジュールとして提供されるため、必要に応じて拡張モジュールを導入してください。

See also

拡張モジュールの一覧やその導入方法については、 Asakusa Gradle Plugin ユーザーガイド や Asakusa Framework デプロイメントガイド を参照してください。

標準プラグインライブラリ

Asakusa Frameworkのデプロイメントアーカイブには、デフォルトのWindGate用プラグインライブラリとして、あらかじめ以下のプラグインライブラリと、プラグインライブラリが使用する依存ライブラリが同梱されています。

WindGate標準プラグインライブラリ

プラグインライブラリ

説明

asakusa-windgate-stream

ローカルのファイルシステムと連携するためのプラグイン

asakusa-windgate-jdbc

JDBC経由でDBMSと連携するためのプラグイン

asakusa-windgate-hadoopfs

Hadoopと連携するためのプラグイン

ローカルファイルシステムの入出力

Asakusa FrameworkのバッチアプリケーションからWindGateを利用してローカルファイルシステムの入出力を行うには、対象のプロファイルに ローカルファイルシステムの設定 を追加します。

また、データモデルとバイトストリームをマッピングする DataModelStreamSupport 11 の実装クラスを作成します。この実装クラスは、DMDLコンパイラの拡張を利用して自動的に生成できます。

なお、以降の機能を利用するには次のライブラリやプラグインが必要です 12 。

WindGateで利用するライブラリ等

ライブラリ

概要

asakusa-windgate-vocabulary

DSL用のクラス群

asakusa-windgate-plugin

DSLコンパイラプラグイン

asakusa-windgate-test-moderator

テストドライバープラグイン

asakusa-windgate-dmdl

DMDLコンパイラプラグイン

Hint

Asakusa Gradle Plugin ユーザーガイド の手順に従ってプロジェクトテンプレートから作成したプロジェクトは、これらのライブラリやプラグインがGradle Pluginによってデフォルトで利用可能になっています。

11

com.asakusafw.runtime.directio.DataFormat [https://docs.asakusafw.com/0.10.3/release/api/com/asakusafw/runtime/directio/DataFormat.html]

12

com.asakusafw.windgate.core.vocabulary.DataModelStreamSupport [https://docs.asakusafw.com/0.10.3/release/api/com/asakusafw/windgate/core/vocabulary/DataModelStreamSupport.html]

CSV形式のDataModelStreamSupportの作成

CSV形式 13 に対応した DataModelStreamSupport の実装クラスを自動的に生成するには、対象のデータモデルに @windgate.csv を指定します。

@windgate.csv
document = {
    "the name of this document"
    name : TEXT;

    "the content of this document"
    content : TEXT;
};

上記のように記述してデータモデルクラスを生成すると、 <出力先パッケージ>.csv.<データモデル名>CsvSupport というクラスが自動生成されます。このクラスは DataModelStreamSupport を実装し、データモデル内のプロパティが順番に並んでいるCSVを取り扱えます。

また、 単純な ローカルファイルシステムを利用するインポーター記述 と ローカルファイルシステムを利用するエクスポーター記述 の骨格も自動生成します。前者は <出力先パッケージ>.csv.Abstract<データモデル名>CsvImporterDescription 、後者は <出力先パッケージ>.csv.Abstract<データモデル名>CsvExporterDescription というクラス名で生成します。必要に応じて継承して利用してください。

13

ここでのCSV形式は、 RFC 4180 [https://tools.ietf.org/html/rfc4180.html] で提唱されている形式を拡張したものです。文字セットをASCIIの範囲外にも拡張したり、CRLF以外にもCRのみやLFのみも改行と見なしたり、ダブルクウォート文字の取り扱いを緩くしたりなどの拡張を加えています。 CSV形式の注意点 も参照してください。

CSV形式の設定

@windgate.csv 属性には、次のような要素を指定できます。

CSV形式の設定

要素

型

既定値

内容

charset

文字列

"UTF-8"

ファイルの文字エンコーディング

has_header

論理値

FALSE

TRUE でヘッダの利用を許可。 FALSE で不許可

force_header

論理値

FALSE

TRUE でヘッダの利用を許可し、ヘッダの形式チェックを行わない。 FALSE で不許可

true

文字列

"true"

BOOLEAN 型の TRUE 値の表現形式

false

文字列

"false"

BOOLEAN 型の FALSE 値の表現形式

date

文字列

"yyyy-MM-dd"

DATE 型の表現形式

datetime

文字列

"yyyy-MM-dd HH:mm:ss"

DATETIME 型の表現形式

なお、 date および datetime には SimpleDateFormat 14 の形式で日付や時刻を指定します。

以下は記述例です。

@windgate.csv(
    charset = "ISO-2022-JP",
    has_header = TRUE,
    true = "1",
    false = "0",
    date = "yyyy/MM/dd",
    datetime = "yyyy/MM/dd HH:mm:ss",
)
model = {
    ...
};

14

java.text.SimpleDateFormat

CSVフィールドの設定

CSVのフィールドに関する設定は、DMDLスクリプトのデータモデルに含まれるそれぞれのプロパティに @windgate.csv.field 属性を指定します。

@windgate.csv.field 属性には、次のような要素を指定できます。

CSVフィールドの設定

要素

型

既定値

内容

name

文字列

プロパティ名

CSV形式の設定 でヘッダを有効にしている場合に使用するCSVのヘッダのフィールド名

quote

文字列

default

各フィールド値のクォートに関する動作の指定。default , needed , always のいずれかを指定

name 要素に指定するフィールド名は、入力データの読み込み時のヘッダの形式チェックやデータ出力時のヘッダ文字列として使用されます。

quote 要素に関する動作の指定は以下の通りです。

needed : フィールド値にクォート処理が必要な値が含まれている場合にクォート処理を行う

always : フィールド値の内容に関わらず、常にクォート処理を行う

default : needed を指定した場合と同じ動作を行う

以下はCSVフィールドの設定を付加したDMDLスクリプトの記述例です。

@windgate.csv
document = {
    "the name of this document"
    @windgate.csv.field(name = "題名" , quote = "always")
    name : TEXT;

    "the content of this document"
    @windgate.csv.field(name = "内容" , quote = "needed")
    content : TEXT;
};

ファイル情報の取得

解析中のCSVファイルに関する属性を取得する場合、それぞれ以下の属性をプロパティに指定します。

ファイル情報の取得に関する属性

属性

型

内容

@windgate.csv.file_name

TEXT

ファイル名

@windgate.csv.line_number

INT , LONG

テキスト行番号 (1起算)

@windgate.csv.record_number

INT , LONG

レコード番号 (1起算)

上記の属性が指定されたプロパティは、CSVのフィールドから除外されます。

Attention

これらの属性はCSVの解析時のみ有効です。 CSVを書き出す際には無視されます。

CSVから除外するプロパティ

特定のプロパティをCSVのフィールドとして取り扱いたくない場合、プロパティに @windgate.csv.ignore を指定します。

CSV形式の注意点

自動生成でサポートするCSV形式を利用するうえで、いくつかの注意点があります。

CSVに空の文字列を書き出しても、読み出し時に null として取り扱われます

論理値は復元時に、値が true で指定した文字列の場合には true , 空の場合には null , それ以外の場合には false となります

ヘッダが一文字でも異なる場合、解析時にヘッダとして取り扱われません

1レコードが10MBを超える場合、正しく解析できません

ローカルファイルシステムを利用するインポーター記述

WindGateと連携してファイルからデータをインポートする場合、 FsImporterDescription 15 クラスのサブクラスを作成して必要な情報を記述します。

このクラスでは、下記のメソッドをオーバーライドします。

String getProfileName()

インポーターが使用するプロファイル名を戻り値に指定します。

String getPath()

インポート対象のファイルパスを resource.local.basePath からの相対パスで指定します。

ここには ${変数名} の形式で、バッチ起動時の引数やあらかじめ宣言された変数を利用できます。利用可能な変数はコンテキストAPIで参照できるものと同様です。

Class<?> getModelType()

インポーターが処理対象とするデータモデルオブジェクトの型を表すクラスを戻り値に指定します。

このメソッドは、自動生成される骨格ではすでに宣言されています。

Class<? extends DataModelStreamSupport<?>> getStreamSupport()

DataModelStreamSupport の実装クラスを戻り値に指定します。

このメソッドは、自動生成される骨格ではすでに宣言されています。

以下は実装例です。

public class DocumentFromFile extends FsImporterDescription {

    @Override
    public Class<?> getModelType() {
        return Document.class;
    }

    @Override
    public String getProfileName() {
        return "example";
    }

    @Override
    public String getPath() {
        return "example/input.csv";
    }

    @Override
    public Class<? extends DataModelStreamSupport<?>> getStreamSupport() {
        return DocumentCsvSupport.class;
    }
}

15

com.asakusafw.vocabulary.windgate.FsImporterDescription [https://docs.asakusafw.com/0.10.3/release/api/com/asakusafw/vocabulary/windgate/FsImporterDescription.html]

ローカルファイルシステムを利用するエクスポーター記述

WindGateと連携してジョブフローの処理結果をローカルのファイルに書き出すには、 FsExporterDescription 16 クラスのサブクラスを作成して必要な情報を記述します。

このクラスでは、下記のメソッドをオーバーライドします。

String getProfileName()

エクスポーターが使用するプロファイル名を戻り値に指定します。

String getPath()

エクスポート対象のファイルパスを resource.local.basePath からの相対パスで指定します。

ここには ${変数名} の形式で、バッチ起動時の引数やあらかじめ宣言された変数を利用できます。利用可能な変数はコンテキストAPIで参照できるものと同様です。

Class<?> getModelType()

エクスポーターが処理対象とするデータモデルオブジェクトの型を表すクラスを戻り値に指定します。

このメソッドは、自動生成される骨格ではすでに宣言されています。

Class<? extends DataModelStreamSupport<?>> getStreamSupport()

DataModelStreamSupport の実装クラスを戻り値に指定します。

このメソッドは、自動生成される骨格ではすでに宣言されています。

Attention

getPath() で指定した出力先に既にファイルが存在する場合、エクスポート時に上書きされます。

以下は実装例です。

public class WordIntoFile extends FsExporterDescription {

    @Override
    public Class<?> getModelType() {
        return Word.class;
    }

    @Override
    public String getProfileName() {
        return "example";
    }

    @Override
    public String getPath() {
        return "example/output.csv";
    }

    @Override
    public Class<? extends DataModelStreamSupport<?>> getStreamSupport() {
        return WordCsvSupport.class;
    }
}

16

com.asakusafw.vocabulary.windgate.FsExporterDescription [https://docs.asakusafw.com/0.10.3/release/api/com/asakusafw/vocabulary/windgate/FsExporterDescription.html]

データベースの入出力

Asakusa FrameworkのバッチアプリケーションからWindGateを利用してデータベースの入出力を行うには、対象のプロファイルに データベースの設定 を追加します。

また、データモデルと PreparedStatement , ResultSet をマッピングする DataModelJdbcSupport 17 の実装クラスを作成します。この実装クラスは、DMDLコンパイラの拡張を利用して自動的に生成できます。

なお、以降の機能を利用するには次のライブラリやプラグインが必要です。

WindGateで利用するライブラリ等

ライブラリ

概要

asakusa-windgate-vocabulary

DSL用のクラス群

asakusa-windgate-plugin

DSLコンパイラプラグイン

asakusa-windgate-test-moderator

テストドライバープラグイン

asakusa-windgate-dmdl

DMDLコンパイラプラグイン

Hint

Asakusa Gradle Plugin ユーザーガイド の手順に従ってプロジェクトテンプレートから作成したプロジェクトは、これらのライブラリやプラグインがGradle Pluginによってデフォルトで利用可能になっています。

17

com.asakusafw.windgate.core.vocabulary.DataModelJdbcSupport [https://docs.asakusafw.com/0.10.3/release/api/com/asakusafw/windgate/core/vocabulary/DataModelJdbcSupport.html]

DataModelJdbcSupportの自動生成

データモデルから DataModelJdbcSupport の実装クラスを自動的に生成するには、それぞれのプロパティに @windgate.jdbc.column を指定してさらに name 要素で対応するカラム名を記述します。また、テーブル名を指定するにはデータモデルに @windgate.jdbc.table を指定して name 要素内に記述します 18 。

@windgate.jdbc.table(name = "DOCUMENT")
document = {
    "the name of this document"
    @windgate.jdbc.column(name = "NAME")
    name : TEXT;

    "the content of this document"
    @windgate.jdbc.column(name = "CONTENT")
    content : TEXT;
};

上記のように記述してデータモデルクラスを生成すると、 <出力先パッケージ>.jdbc.<データモデル名>JdbcSupport というクラスが自動生成されます。このクラスは DataModelJdbcSupport を実装し、 @windgate.jdbc.column で指定したカラムが利用可能です。

また、 @windgate.jdbc.table を指定した場合、単純な データベースを利用するインポーター記述 と データベースを利用するエクスポーター記述 の骨格も自動生成します。前者は <出力先パッケージ>.jdbc.Abstract<データモデル名>JdbcImporterDescription 、後者は <出力先パッケージ>.jdbc.Abstract<データモデル名>JdbcExporterDescription というクラス名で生成します。

この自動生成されたインポーター/エクスポーター記述の骨格は指定されたテーブルのすべてのカラムを利用します。必要に応じて継承して利用してください。

18

@windgate.jdbc.table の指定は必須ではありません。

DMDLとJDBCの型の対応

DMDLとJDBCの型の対応は以下の通りです。

DMDLとJavaとJDBCのデータ型

説明

DMDL

Javaクラス

JDBC

32bit符号付き整数

INT

int (IntOption)

int

64bit符号付き整数

LONG

long (LongOption)

long

単精度浮動小数点

FLOAT

float (FloatOption)

float

倍精度浮動小数点

DOUBLE

double (DoubleOption)

double

文字列

TEXT

Text (StringOption)

String

10進数

DECIMAL

BigDecimal (DecimalOption)

BigDecimal

日付

DATE

Date (DateOption)

java.sql.Date

日時

DATETIME

DateTime (DateTime)

java.sql.Timestamp

論理値

BOOLEAN

boolean (BooleanOption)

boolean

8bit符号付き整数

BYTE

byte (ByteOption)

byte

16bit符号付き整数

SHORT

short (ShortOption)

short

データベースを利用するインポーター記述

WindGateと連携してデータベースのテーブルからデータをインポートする場合、 JdbcImporterDescription 19 クラスのサブクラスを作成して必要な情報を記述します。

このクラスでは、下記のメソッドをオーバーライドします。

String getProfileName()

インポーターが使用するプロファイル名を戻り値に指定します。

Class<?> getModelType()

インポーターが処理対象とするデータモデルオブジェクトの型を表すクラスを戻り値に指定します。

このメソッドは、自動生成される骨格ではすでに宣言されています。

String getTableName()

インポート対象のテーブル名を戻り値に指定します。

このメソッドは、自動生成される骨格ではすでに宣言されています。

List<String> getColumnNames()

インポート対象のカラム名を戻り値に指定します。ここで指定したカラム名のみインポートを行います。

このメソッドは、自動生成される骨格ではすでに宣言されています。

Class<? extends DataModelJdbcSupport<?>> getJdbcSupport()

DataModelJdbcSupport の実装クラスを戻り値に指定します。

このメソッドは、自動生成される骨格ではすでに宣言されています。

String getCondition()

インポーターが利用する抽出条件をSQLの条件式で指定します（省略可能）。

指定する文字列はSQL文の WHERE 句以降の文字列（ WHERE の部分は不要）である必要があります。省略時にはテーブル全体を入力の対象にとります。

ここには ${変数名} の形式で、バッチ起動時の引数やあらかじめ宣言された変数を利用できます。利用可能な変数はコンテキストAPIで参照できるものと同様です。変数がそのまま文字列として展開されるため、文字列リテラルを利用する場合などには注意が必要です。

Collection<? extends JdbcAttribute> getOptions()

インポート処理時に指定するオプションを指定します。

指定可能なオプションは、列挙型 JdbcImporterDescription.Option 20 に定義されています。本バージョンでは、以下のオプションが利用可能です。

データベースを利用するインポータ記述で利用可能なオプション

オプション

内容

ORACLE_PARTITION

Oracleのパーティションテーブルに対する並列読み込みを有効にする。

この機能を利用する場合、WindGateの実行環境は WindGate JDBC ダイレクト・モード を利用する必要がある。また WindGate JDBC ダイレクト・モード の実行環境では、このオプション指定に加えて JDBCドライバーの配置 で com.asakusafw.dag.jdbc.<profile-name>.optimizations を設定する必要がある。

以下は実装例です。

public class DocumentFromDb extends JdbcImporterDescription {

    @Override
    public Class<?> getModelType() {
        return Document.class;
    }

    @Override
    public String getProfileName() {
        return "example";
    }

    @Override
    public String getTableName() {
        return "DOCUMENT";
    }

    @Override
    public List<String> getColumnNames() {
        return Arrays.asList("NAME", "CONTENT");
    }

    @Override
    public Class<? extends DataModelJdbcSupport<?>> getJdbcSupport() {
        return DocumentJdbcSupport.class;
    }

    @Override
    public Collection<JdbcAttribute> getOptions() {
        return Arrays.asList(Option.ORACLE_PARTITION);
    }
}

19

com.asakusafw.vocabulary.windgate.JdbcImporterDescription [https://docs.asakusafw.com/0.10.3/release/api/com/asakusafw/vocabulary/windgate/JdbcImporterDescription.html]

20

com.asakusafw.vocabulary.windgate.JdbcImporterDescription.Option [https://docs.asakusafw.com/0.10.3/release/api/com/asakusafw/vocabulary/windgate/JdbcImporterDescription.Option.html]

データベースを利用するエクスポーター記述

WindGateと連携してジョブフローの処理結果をデータベースのテーブルに書き出すには、 JdbcExporterDescription 21 クラスのサブクラスを作成して必要な情報を記述します。

このクラスでは、下記のメソッドをオーバーライドします。

String getProfileName()

エクスポーターが使用するプロファイル名を戻り値に指定します。

Class<?> getModelType()

エクスポーターが処理対象とするデータモデルオブジェクトの型を表すクラスを戻り値に指定します。

このメソッドは、自動生成される骨格ではすでに宣言されています。

String getTableName()

エクスポート対象のテーブル名を戻り値に指定します。

このメソッドは、自動生成される骨格ではすでに宣言されています。

List<String> getColumnNames()

エクスポート対象のカラム名を戻り値に指定します。ここで指定したカラム名のみエクスポートを行います。

このメソッドは、自動生成される骨格ではすでに宣言されています。

String getCustomTruncate()

テーブルの内容を削除する際のクエリー文を指定します。省略時には データベースの設定 に従ったクエリーが実行されます。

ここには ${変数名} の形式で、バッチ起動時の引数やあらかじめ宣言された変数を利用できます。利用可能な変数はコンテキストAPIで参照できるものと同様です。変数がそのまま文字列として展開されるため、文字列リテラルを利用する場合などには注意が必要です。

Class<? extends DataModelJdbcSupport<?>> getJdbcSupport()

DataModelJdbcSupport の実装クラスを戻り値に指定します。

このメソッドは、自動生成される骨格ではすでに宣言されています。

Collection<? extends JdbcAttribute> getOptions()

エクスポート処理時に指定するオプションを指定します。

指定可能なオプションは、列挙型 JdbcExporterDescription.Option 22 に定義されています。本バージョンでは、以下のオプションが利用可能です。

データベースを利用するエクスポーター記述で利用可能なオプション

オプション

内容

ORACLE_DIRPATH

Oracleのダイレクト・パス・インサートを有効にする。実行するINSERT文に対して、APPEND_VALUESヒントを指定する。

WindGateの実行環境でダイレクト・パス・インサートを利用にするには、このオプション指定に加えて データベースの設定 で resource.jdbc.optimizations を設定する必要がある。

以下は実装例です。

public class WordIntoDb extends JdbcExporterDescription {

    @Override
    public Class<?> getModelType() {
        return Word.class;
    }

    @Override
    public String getProfileName() {
        return "example";
    }

    @Override
    public String getTableName() {
        return "WORD";
    }

    @Override
    public List<String> getColumnNames() {
        return Arrays.asList("STRING", "FREQUENCY");
    }

    @Override
    public Class<? extends DataModelJdbcSupport<?>> getJdbcSupport() {
        return WordJdbcSupport.class;
    }

    @Override
    public Collection<Option> getOptions() {
        return Arrays.asList(Option.ORACLE_DIRPATH);
    }
}

21

com.asakusafw.vocabulary.windgate.JdbcExporterDescription [https://docs.asakusafw.com/0.10.3/release/api/com/asakusafw/vocabulary/windgate/JdbcExporterDescription.html]

22

com.asakusafw.vocabulary.windgate.JdbcExporterDescription.Option [https://docs.asakusafw.com/0.10.3/release/api/com/asakusafw/vocabulary/windgate/JdbcExporterDescription.Option.html]

WindGateと連携したテスト

WindGateを利用したジョブフローやバッチのテストは、Asakusa Frameworkの通常のテスト方法で行えます。通常のテストについては アプリケーションのテスト - TestDriver を参照してください。

Attention

テストドライバーは、テストのたびにWindGateのプラグイン用のClassLoaderを作成し、プラグインライブラリをクラスパスに通します。

クラスロードに関する問題が発生した場合には、テストを実行する際のクラスパスにそれらのライブラリを含めてください。

WindGateに関するログ一覧

この文書では、WindGateが利用するログの一覧を紹介します。

WindGate本体のログ

WindGateのプラグイン部分を除く本体が出力するログは以下の通りです。

WindGate本体のログ

ログコード

レベル

概要

WG-BOOT-I00000

情報

WindGate全体を開始

WG-BOOT-I00999

情報

WindGate全体を終了

WG-BOOT-E00001

エラー

WindGate全体の初期化に失敗した

WG-BOOT-E00002

エラー

WindGate全体のデータ処理に失敗した

WG-BOOT-I01000

情報

WindGateのファイナライズ処理を開始

WG-BOOT-I01999

情報

WindGateのファイナライズ処理を終了

WG-BOOT-E01001

エラー

WindGateのファイナライズの初期化に失敗した

WG-BOOT-E01002

エラー

WindGateのファイナライズ処理に失敗した

WG-BOOT-W99001

警告

指定のプラグインをロードできなかった

WG-BOOT-W99002

警告

実行時引数の直列化形式が正しくない

WG-BOOT-W99003

警告

実行時引数の直列化形式で同一の引数が複数回宣言されている

WG-CORE-I00000

情報

WindGateの処理を開始

WG-CORE-I00999

情報

WindGateの処理を終了

WG-CORE-I00001

情報

セッションを開始している

WG-CORE-I00002

情報

リソースをロードしている

WG-CORE-I00003

情報

リソースの初期処理を行なっている

WG-CORE-I00004

情報

データ転送のためにリソースを準備している

WG-CORE-I00005

情報

データ転送を開始している

WG-CORE-I00006

情報

リソースの終了処理を行なっている

WG-CORE-I00007

情報

セッションを終了している

WG-CORE-I00008

情報

WindGateの処理が成功

WG-CORE-W00001

警告

セッションの終了に失敗した

WG-CORE-W00002

警告

WindGateの処理は割り込みにより中断した

WG-CORE-W00003

警告

WindGateの処理は例外により失敗した

WG-CORE-W00004

警告

WindGateの処理は別の問題によりキャンセルされた

WG-CORE-E00001

エラー

リソースの初期化処理に失敗した

WG-CORE-E00002

エラー

リソースの準備に失敗した

WG-CORE-E00003

エラー

データ転送に失敗した

WG-CORE-E00004

エラー

リソースの終了処理に失敗した

WG-CORE-I01000

情報

ファイナライズの処理を開始

WG-CORE-I01999

情報

ファイナライズの処理を終了

WG-CORE-I01001

情報

ファイナライズ対象のセッションを開始している

WG-CORE-I01002

情報

指定したセッションはすでに完了している

WG-CORE-I01003

情報

リソースのファイナライズ処理を行なっている

WG-CORE-I01004

情報

セッションのファイナライズを行なっている

WG-CORE-I01005

情報

ファイナライズの処理が成功

WG-CORE-W01001

警告

セッションのファイナライズに失敗した

WG-CORE-W01002

警告

リソースのファイナライズに失敗した

WG-CORE-W01003

警告

ファイナライズ対象のセッションの終了処理に失敗した

WG-CORE-W02001

警告

プロファイルに余計な項目が記載されていた

WG-CORE-E02001

エラー

プラグインクラスのロードに失敗した

WG-CORE-E02002

エラー

プラグインクラスのインスタンス化に失敗した

WG-CORE-E02003

エラー

プロファイルのcoreセクションが間違っていた

WG-CORE-E02004

エラー

プロファイルのresourceセクションの構造が間違っていた

WG-CORE-E02005

エラー

プロファイルのキーに利用できない名前が含まれていた

WG-CORE-E02006

エラー

プロファイルのsessionセクションが間違っていた

WG-CORE-E03001

エラー

データ転送内容を表すスクリプトが間違っていた

WG-CORE-E03002

エラー

データ転送に利用するデータモデルクラスをロードできなかった

WG-CORE-E04001

エラー

データ転送に利用するリソースが定義されていなかった

WG-CORE-E04002

エラー

プロファイルのresourceセクションの値が間違っていた

WG-CORE-I05000

情報

データ転送プロセスを開始

WG-CORE-I05999

情報

データ転送プロセスを終了

WG-CORE-I05001

情報

データ転送プロセスが成功

WG-CORE-E05001

エラー

データ転送プロセスの実行に失敗した

WG-CORE-E05002

エラー

データ転送の入力を終了するのに失敗した

WG-CORE-E05003

エラー

データ転送の出力を終了するのに失敗した

WG-CORE-E05004

エラー

データ転送に利用するデータモデルクラスのインスタンス化に失敗した

WG-CORE-E99001

エラー

プロファイル内に未定義の環境変数が指定された

ローカルファイルシステムを利用したセッションに関するログ

プロファイルの session セクションに com.asakusafw.windgate.file.session.FileSessionProvider を指定した場合の、対応する部分のログは以下の通りです。

ローカルファイルシステムを利用したセッションに関するログ

ログコード

レベル

概要

WG-FILE_SESSION-E00001

エラー

プロファイルのsessionセクション以下に未定義の環境変数が指定された

WG-FILE_SESSION-E00002

エラー

セッション情報を格納するストレージを初期化出来なかった

WG-FILE_SESSION-W01001

警告

セッションファイルが破損している

WG-FILE_SESSION-E01001

エラー

セッションのアタッチに失敗した

WG-FILE_SESSION-W02001

警告

セッションファイルのロックを取得できなかった

WG-FILE_SESSION-W02002

警告

セッションファイルを閉じられなかった

WG-FILE_SESSION-E02001

エラー

セッションファイルの無効化に失敗した

WG-FILE_SESSION-E02002

エラー

セッションのデタッチに失敗した

再試行可能なデータ転送プロセスに関するログ

プロファイルの process.basic セクションに com.asakusafw.windgate.retryable.RetryableProcessProvider を指定した場合の、対応する部分のログは以下の通りです。

再試行可能なデータ転送プロセスに関するログ

ログコード

レベル

概要

WG-RETRY-E00001

エラー

プロファイル内のプロセス設定が正しくない

WG-RETRY-E00002

エラー

実際に転送を行うプロセスを初期化出来なかった

WG-RETRY-I01000

情報

再試行を行うプロセスを開始

WG-RETRY-I01999

情報

再試行を行うプロセスを終了

WG-RETRY-I01001

情報

再試行を行うプロセスが成功

WG-RETRY-W01001

警告

データ転送の試行に失敗したため、次回の試行を行おうとしている

WG-RETRY-E01001

エラー

データ転送のすべての試行に失敗した

WG-RETRY-E01002

エラー

データ転送中に割り込み要求が行われたため、すべての試行を中断した

同一環境上のHadoopを利用するリソースに関するログ

プロファイルの resource.hadoop セクションに com.asakusafw.windgate.hadoopfs.HadoopFsProvider を指定した場合の、対応する部分のログは以下の通りです。

同一環境上のHadoopを利用するリソースに関するログ

ログコード

レベル

概要

WG-HADOOP_FS-I00001

情報

(廃止) シーケンスファイルの圧縮に利用する圧縮コーデッククラスの情報

WG-HADOOP_FS-W00001

警告

シーケンスファイルの圧縮に利用する圧縮コーデッククラスが指定されていた

WG-HADOOP_FS-E00001

エラー

プロファイル内のリソースの設定が正しくない

WG-HADOOP_FS-E00002

エラー

Hadoop File Systemの初期化に失敗した

WG-HADOOP_FS-W01001

警告

データ転送に絶対パスが指定された

WG-HADOOP_FS-E01001

エラー

データ転送の内容が正しくない

WG-HADOOP_FS-E01002

エラー

データ転送に利用するデータモデルクラスが正しくない

WG-HADOOP_FS-W03001

警告

Hadoop File Systemからの入力を閉じるのに失敗した

WG-HADOOP_FS-W04001

警告

Hadoop File Systemへの出力を閉じるのに失敗した

WG-HADOOP_FS-I09001

情報

対象のパスを解決している

WG-HADOOP_FS-I09002

情報

テンポラリファイルを読み込み用に開いている

WG-HADOOP_FS-W09001

警告

テンポラリファイルを閉じられなかった

SSH経由でリモートのHadoopを利用するリソースに関するログ

プロファイルの resource.hadoop セクションに com.asakusafw.windgate.hadoopfs.jsch.JschHadoopFsProvider を指定した場合の、対応する部分のログは以下の通りです。

SSH経由でリモートのHadoopを利用するリソースに関するログ

ログコード

レベル

概要

WG-HADOOP_FS-I10001

情報

(廃止) シーケンスファイルの圧縮に利用する圧縮コーデッククラスの情報

WG-HADOOP_FS-W10001

警告

シーケンスファイルの圧縮に利用する圧縮コーデッククラスが指定されていた

WG-HADOOP_FS-E10001

エラー

プロファイル内のリソースの設定が正しくない

WG-HADOOP_FS-E11001

エラー

データ転送の内容が正しくない

WG-HADOOP_FS-E11002

エラー

データ転送に利用するデータモデルクラスが正しくない

WG-HADOOP_FS-W13001

警告

入力データに関するコネクションのクローズに失敗した

WG-HADOOP_FS-E13001

エラー

入力データに関するリモートコマンドの終了に失敗した

WG-HADOOP_FS-W14001

警告

出力データに関するコネクションのクローズに失敗した

WG-HADOOP_FS-E14001

エラー

出力データに関するリモートコマンドの終了に失敗した

WG-HADOOP_FS-W19001

警告

データ転送プロトコルが正しくない

WG-HADOOP_FS-W19002

警告

データ転送プロトコルが始まる前に余計なメッセージが含まれている

WG-HADOOP_FS-I20000

情報

remote getコマンドを開始

WG-HADOOP_FS-I20999

情報

remote getコマンドを終了

WG-HADOOP_FS-I20001

情報

remote getコマンドの通信プロトコルを初期化

WG-HADOOP_FS-I20002

情報

remote getコマンドの通信プロトコルを終了

WG-HADOOP_FS-I20003

情報

remote getコマンドで転送するファイルパスを解決

WG-HADOOP_FS-I20004

情報

remote getコマンドでファイルの転送を開始

WG-HADOOP_FS-I20005

情報

remote getコマンドでファイルの転送を終了

WG-HADOOP_FS-E20001

エラー

remote getコマンドでコマンド起動引数が正しくなかった

WG-HADOOP_FS-E20002

エラー

remote getコマンドでファイルの転送に失敗した

WG-HADOOP_FS-E20003

エラー

remote getコマンドでファイルの転送がキャンセルされた

WG-HADOOP_FS-I21000

情報

remote putコマンドを開始

WG-HADOOP_FS-I21999

情報

remote putコマンドを終了

WG-HADOOP_FS-I21001

情報

remote putコマンドの通信プロトコルを初期化

WG-HADOOP_FS-I21002

情報

remote putコマンドの通信プロトコルを終了

WG-HADOOP_FS-I21003

情報

remote putコマンドでファイルの転送を開始

WG-HADOOP_FS-I21004

情報

remote putコマンドでファイルの転送を終了

WG-HADOOP_FS-E21001

エラー

remote putコマンドでコマンド起動引数が正しくなかった

WG-HADOOP_FS-E21002

エラー

remote putコマンドでファイルの転送がキャンセルされた

WG-HADOOP_FS-I30001

情報

JSchを利用してSSHセッションを開始

WG-HADOOP_FS-I30002

情報

JSchを利用してSSHセッションを開始した

WG-HADOOP_FS-I30003

情報

JSchを利用してリモートコマンドを起動

WG-HADOOP_FS-I30004

情報

JSchを利用してリモートコマンドを起動した

WG-HADOOP_FS-W30001

警告

JSchを利用したリモートコマンド起動に、環境変数が指定されようとしたため省略した

WG-HADOOP_FS-E30001

エラー

JSchを利用したSSHセッションの開始に失敗した

WG-HADOOP_FS-E30002

エラー

JSchを利用したリモートコマンドの起動に失敗した

WG-HADOOP_FS-E30003

エラー

JSchを利用したリモートコマンドの終了に失敗した (タイムアウト)

ローカルファイルシステムを利用するリソースに関するログ

プロファイルの resource.local セクションに com.asakusafw.windgate.stream.file.FileResourceProvider を指定した場合の、対応する部分のログは以下の通りです。

ローカルファイルシステムを利用するリソースに関するログ

ログコード

レベル

概要

WG-STREAM-E00001

エラー

プロファイル内のリソース設定が正しくない

WG-STREAM-E01001

エラー

データ転送の内容が正しくない

WG-STREAM-E01002

エラー

DataModelStreamSupport オブジェクトの初期化に失敗した

WG-STREAM-I03001

情報

入力ストリームを開いている

WG-STREAM-I03002

情報

入力ストリームを閉じている

WG-STREAM-W03001

警告

入力ストリームを閉じられなかった

WG-STREAM-E03001

エラー

入力ストリームを開けなかった

WG-STREAM-I04001

情報

出力ストリームを開いている

WG-STREAM-I04002

情報

出力ストリームを閉じている

WG-STREAM-E04001

エラー

出力ストリームを開けなかった

WG-STREAM-E04002

エラー

出力ストリームを閉じられなかった

データベースを利用するリソースに関するログ

プロファイルの resource.jdbc セクションに com.asakusafw.windgate.jdbc.JdbcResourceProvider を指定した場合の、対応する部分のログは以下の通りです。

データベースを利用するリソースに関するログ

ログコード

レベル

概要

WG-JDBC-E00001

エラー

プロファイル内のリソース設定が正しくない

WG-JDBC-E00002

エラー

データベースのコネクションを開けなかった

WG-JDBC-W00001

警告

データベースのコネクションを再度開こうとしている

WG-JDBC-E01001

エラー

データ転送の内容が正しくない

WG-JDBC-E01002

エラー

DataModelJdbcSupport オブジェクトの初期化に失敗した

WG-JDBC-I02001

情報

データベースのコネクションを開いている

WG-JDBC-W02001

警告

データベースのコネクションを閉じられなかった

WG-JDBC-I03001

情報

データベースからのデータ取得を開始している

WG-JDBC-I03002

情報

データベースからのデータ取得を開始した

WG-JDBC-W03001

警告

データを取得するステートメントの破棄に失敗した

WG-JDBC-E03001

エラー

データベースからのデータ取得に失敗した

WG-JDBC-I04001

情報

データベースのテーブルクリアを行なっている

WG-JDBC-W04001

警告

データを書き出すステートメントの破棄に失敗した

WG-JDBC-E04001

エラー

データベースのテーブルクリアに失敗した

WG-JDBC-E04002

エラー

データを書き出すステートメントの作成に失敗した

WG-JDBC-E04003

エラー

書き出すデータの準備に失敗した

WG-JDBC-E04004

エラー

データの書き出しに失敗した

WindGate開発者ガイド

この文書では、WindGateの拡張方法について紹介します。

Todo

WindGate > Developer Guide

WindGate TSV

この文書では、WindGateを使ってTSVフォーマットのローカルファイルをインポート/エクスポートするための拡張機能の使い方について説明します。

Deprecated

Asakusa Framework バージョン 0.10.0 以降、 WindGate TSV は非推奨機能となりました。代わりに WindGate CSV や、 Direct I/O formatted text を利用してください。

Mavenアーティファクト

WindGateのTSVファイル連携モジュールはAsakusa FrameworkのMavenリポジトリにグループID com.asakusafw.sandbox を持つMavenアーティファクトとして登録されています。

WindGateのTSVファイル連携で使用するMavenアーティファクト

グループID

アーティファクトID

com.asakusafw.sandbox

asakusa-windgate-dmdl-ext

TSVファイル連携モジュールの利用方法

TSVファイル連携モジュールを使用する場合はアプリケーションプロジェクトの build.gradle の dependencies ブロック内に依存定義を追加します。

build.gradle

dependencies {
    compile group: 'com.asakusafw.sandbox', name: 'asakusa-windgate-dmdl-ext', version: asakusafw.core.version
}

モデルクラスの生成

DMDLに対するTSVファイル用拡張属性の追加

TSVファイル連携を行うために、DMDLに対してTSVファイルを扱うことを示す拡張属性を追加します。

各モデルのDMDLスクリプトに対して、モデル名の記述行の前行に拡張属性 @windgate.stream_format(type="tsv") を付与します。

以下にTSVファイルを扱う場合のDMDLスクリプトの例を示します。

"テーブルEX1"
...
@windgate.stream_format(type="tsv")
ex1 = {
    "SID"
    sid : LONG;
    "VALUE"
    value : INT;
    "STRING"
    string : TEXT;
};

Asakusa DSLの記述

WindGateのTSVファイル連携を使った場合のAsakusa DSLの記述については、CSVファイル連携を使った場合と同じです。

TSVファイルフォーマット仕様

WindGateのTSV連携機能で扱うTSVファイルのフォーマット仕様について説明します。

Warning

現時点では、本項のTSVファイルフォーマットは暫定仕様です。

TSVフォーマット概要

TSVファイルは、MySQLの SELECT ... INTO OUTFILE で、次の指定をした場合に生成されるファイルフォーマット 1 と同一です。

FIELDS TERMINATED BY '\t' ENCLOSED BY '' ESCAPED BY '\\'

LINES TERMINATED BY '\n' STARTING BY ''

1

MySQL 5.1 のデフォルトフォーマットと同一です。

TSVフォーマット詳細

各フィールドをDMDLスクリプトの順番に記述します。

フィールドの区切り文字にはタブ文字を使用します。

レコードの区切り文字は改行(LF)を使用します。

CR+LF は使用できません。

エスケープ文字には「\」を使用します。

エスケープ文字そのもの、改行(LF)、タブ文字をデータとして扱う場合は「\」を前に付加してエスケープします。

引用文字は使用しません。

最終レコードにも(LF)が必要です。

エンコーディングはUTF-8を使用します。

NULL値は「\N」で表します。

空文字はフィールド区切り文字間に何も文字を入れないことで表現します。

指数表記は使用しません。

Booleanは0/1で表します。

0:false , 1:true

Date, Datetimeは以下の書式で表します。

Date: YYYY-MM-DD

Datetime: YYYY-MM-DD HH:MM:SS

TSVファイルのサンプル

DMDLスクリプトに対応するTSVファイルの例を以下に示します。

サンプル:DMDLスクリプト

"テーブルEX1"
...
@windgate.stream_format(type="tsv")
ex1 = {
    "SID"
    sid : LONG;
    "VALUE"
    value : INT;
    "STRING"
    string : TEXT;
};

サンプル:TSVファイル

Attention

以下サンプルのドキュメント上の区切り文字はスペースになっていますが、実際のファイルはタブ文字を使用してください。

1   111     hoge1
2   222     fuga2
3   333     bar3
4   111     hoge4
5   222     fuga5
6   333     bar6
7   111     hoge7
8   222     fuga8
9   444     bar9

アプリケーションの実行 - YAESS

YAESSはAsakusa Frameworkで開発したバッチを実行するためのツールです。このツールは、バッチを実行する様々な環境にあわせて、自由に実行方法をカスタマイズできるように作成されています。

YAESSの主な用途は下記のとおりです。

バッチを開発環境やテスト環境上で試験的に実行する

ジョブ管理ツールからYAESSを経由してバッチを実行する

他のツールにYAESSをライブラリとして組み込んで利用する

関連するドキュメント

YAESSスタートガイド

YAESSユーザーガイド

ジョブ実行クラスターの振り分け

YAESS JobQueue

YAESSに関するログ一覧

YAESSスタートガイド

この文書では、 Asakusa Framework スタートガイド の構成で、YAESSの使い方について簡単に紹介します。

See also

YAESSのより詳しい情報は YAESSユーザーガイド を参照してください。

開発環境でのYAESSの実行

Asakusa Framework スタートガイド や Asakusa Gradle Plugin ユーザーガイド の手順で作成されたプロジェクトでは、バッチアプリケーションのビルド構成に、あらかじめYAESSと連携するための設定が含まれています。

バッチの実行

YAESSを使ってバッチを実行するには、コマンドラインから $ASAKUSA_HOME/yaess/bin/yaess-batch.sh <バッチID> と入力します。また、バッチに起動引数を指定する場合、コマンドラインの末尾に -A <変数名>=<値> のように記述します。

$ASAKUSA_HOME/yaess/bin/yaess-batch.sh example.summarizeSales -A date=2011-04-01

出力の最後に Finished: SUCCESS と表示されればバッチ処理は成功です。また、バッチ処理の結果はコマンドの終了コードでも確認できます。 YAESSではUnixの方式に従い、正常終了の場合は 0 , それ以外の場合は 0 でない終了コードを返します。

Starting YAESS
     Profile: /home/asakusa/asakusa/yaess/conf/yaess.properties
      Script: /home/asakusa/asakusa/batchapps/example.summarizeSales/etc/yaess-script.properties
    Batch ID: example.summarizeSales
...

Finished: SUCCESS

Attention

YAESSでバッチアプリケーションを実行するには、バッチアプリケーションが規定のディレクトリにデプロイ済みである必要があります。開発環境にバッチコンパイルしたアプリケーションをデプロイする方法については、 Asakusa Framework スタートガイド などを参照してください。

ワークフロー記述

Asakusa DSLで記述したバッチアプリケーションをバッチコンパイル ( ./gradlew compileBatchapp ) すると、バッチアプリケーションにはYAESS用のワークフロー記述としてYAESSスクリプト ( <バッチID>/etc/yaess-script.properties )というファイルが含まれます。 YAESSはYAESSスクリプトの定義内容に基づいてバッチアプリケーションを実行します。

YAESSスクリプトはバッチ全体のワークフローの構造をYAESS向けに表しています。 YAESSスクリプトの内容を確認するには、コマンドラインから $ASAKUSA_HOME/yaess/bin/yaess-explain.sh <バッチアプリケーションのパス>/yaess-script.properties と入力します。

$ASAKUSA_HOME/yaess/bin/yaess-explain.sh $ASAKUSA_HOME/batchapps/example.summarizeSales/etc/yaess-script.properties

この結果、以下のようなJSON形式のバッチの構造が表示されます。

yaess-script.properties

{
  "id": "example.summarizeSales",
  "jobflows": [
    {
      "id": "byCategory",
      "blockers": [],
      "phases": [
        "setup",
        "import",
        "main",
        "epilogue",
        "export",
        "finalize",
        "cleanup"
      ]
    }
  ]
}

実行環境構成の変更

YAESSはプロファイルセットとよぶ実行環境の構成をもっており、これは $ASAKUSA_HOME/yaess/conf/yaess.properties (以降、「構成ファイル」) を編集することでユーザーが自由にカスタマイズすることができます。

例えば、次のようなものを変更できます。

バッチの実行排他制御の仕組み

バッチのログメッセージの通知方法

バッチ内のジョブスケジューリング方法

Hadoopジョブの起動方法

WindGateなどの外部システム連携モジュールの起動方法

ここでは、いくつかの設定を変更する方法について紹介します。

SSHを経由したHadoopの実行

YAESSを利用すると、SSHを経由してリモートコンピューターにログインし、リモートコンピュータ上に導入されているHadoopを利用してHadoopのジョブを発行するような環境構成を作成できます。

ここではそのような構成を行う設定方法を説明します。まず、YAESSをリモートコンピューター上にもインストールしておきます 1 。

次に、ローカルのYAESSの構成ファイル ( $ASAKUSA_HOME/yaess/conf/yaess.properties ) を編集します。既定の構成は以下のようになっており、これはYAESSはローカルのコンピューターにインストールされたHadoopを利用して、Hadoopのジョブを実行するよう設定されています。

yaess.properties

hadoop = com.asakusafw.yaess.basic.BasicHadoopScriptHandler
hadoop.resource = hadoop-master
hadoop.env.HADOOP_CMD = /usr/bin/hadoop
hadoop.env.ASAKUSA_HOME = ${ASAKUSA_HOME}

これをリモートのHadoopを実行するよう変更するため、以下のプロパティの内容に変更してください 2 。

SSHを経由してHadoopを実行する際の設定

名前

値

hadoop

com.asakusafw.yaess.jsch.SshHadoopScriptHandler

hadoop.ssh.user

ログイン先のユーザー名

hadoop.ssh.host

SSHのリモートホスト名

hadoop.ssh.port

SSHのリモートポート番号

hadoop.ssh.privateKey

ローカルの秘密鍵の位置

hadoop.ssh.passPhrase

秘密鍵のパスフレーズ

hadoop.env.HADOOP_CMD

リモートの hadoop コマンドのパス

hadoop.env.ASAKUSA_HOME

リモートのAsakusa Frameworkのインストール先

以下は設定例です。

yaess.properties

hadoop = com.asakusafw.yaess.jsch.SshHadoopScriptHandler
hadoop.ssh.user = hadoop
hadoop.ssh.host = hadoop.example.com
hadoop.ssh.port = 22
hadoop.ssh.privateKey = ${HOME}/.ssh/id_dsa
hadoop.ssh.passPhrase =
hadoop.resource = hadoop-master
hadoop.env.HADOOP_CMD = /usr/bin/hadoop
hadoop.env.ASAKUSA_HOME = /opt/hadoop/asakusa

1

リモートコンピュータでは、実際には $ASAKUSA_HOME/yaess-hadoop のみを利用します。これは「Hadoopブリッジ」というツールで、YAESSからHadoopジョブを起動する際に利用されます。詳しくは YAESSユーザーガイド を参照してください。

2

デフォルトで定義されているローカルのHadoopを実行するための設定は不要なため、これらの行は削除するか、行頭に # を追加してコメントアウトします。

SSHを経由したWindGateの実行

Hadoopと同様に、WindGateなどの外部連携コマンドもSSHを経由してリモートコンピュータから実行できます。

上記と同様、ローカルのYAESSの構成ファイル ( $ASAKUSA_HOME/yaess/conf/yaess.properties ) を編集します。既定の構成は以下のようになっており、これはローカルのコンピューターにインストールされたコマンドを実行するよう設定されています。

yaess.properties

command.* = com.asakusafw.yaess.basic.BasicCommandScriptHandler
command.*.resource = asakusa
command.*.env.HADOOP_CMD = /usr/bin/hadoop
command.*.env.ASAKUSA_HOME = ${ASAKUSA_HOME}

これを、次の内容に変更します。

SSHを経由してコマンドを実行する際の設定

名前

値

command.*

com.asakusafw.yaess.jsch.SshCommandScriptHandler

command.*.ssh.user

ログイン先のユーザー名

command.*.ssh.host

SSHのリモートホスト名

command.*.ssh.port

SSHのリモートポート番号

command.*.ssh.privateKey

ローカルの秘密鍵の位置

command.*.ssh.passPhrase

秘密鍵のパスフレーズ

command.*.env.ASAKUSA_HOME

リモートのAsakusa Frameworkのインストール先

command.*.env.HADOOP_CMD

リモートの hadoop コマンドのパス

以下は設定例です。

yaess.properties

command.* = com.asakusafw.yaess.jsch.SshCommandScriptHandler
command.*.ssh.user = windgate
command.*.ssh.host = windgate.example.com
command.*.ssh.port = 22
command.*.ssh.privateKey = ${HOME}/.ssh/id_dsa
command.*.ssh.passPhrase =
command.*.resource = asakusa
command.*.env.ASAKUSA_HOME = /home/windgate/asakusa

コマンド実行方法の振り分け

複数のWindGateが異なるコンピューターにインストールされている場合、YAESSでは「プロファイル」という考え方でそれぞれのコマンドを振り分けて実行できます。

WindGateには「プロファイル名」という実行構成の名前がそれぞれあります。これらの名前別に実行構成を指定するには、YAESSの構成ファイル ( $ASAKUSA_HOME/yaess/conf/yaess.properties ) 内で command.<構成の名前> から始まる設定を追加します。

以下は asakusa という名前のプロファイルに対するコマンド実行方法の記述です。

yaess.properties

command.asakusa = com.asakusafw.yaess.jsch.SshCommandScriptHandler
command.asakusa.ssh.user = asakusa
command.asakusa.ssh.host = asakusa.example.com
command.asakusa.ssh.port = 22
command.asakusa.ssh.privateKey = ${HOME}/.ssh/id_dsa
command.asakusa.ssh.passPhrase =
command.asakusa.resource = asakusa
command.asakusa.env.HADOOP_CMD = /usr/bin/hadoop
command.asakusa.env.ASAKUSA_HOME = /home/asakusa/asakusa

ここに追加する内容は command.* から始まる内容と同様です。

構成ファイルにあらかじめ記載された command.* という構成は、名前付きのプロファイルが見つからなかった際に利用されます。上記のように名前付きの構成を指定した場合、ターゲット名やプロファイル名が一致すれば名前付きの構成が優先されます。

YAESSユーザーガイド

この文書では、YAESSの利用方法について紹介します。

Asakusa Frameworkのバッチ構造

YAESSを利用し、その機能を適切に設定するためにはAsakusa Frameworkのバッチ構造を理解しておく必要があります。

バッチの構成要素

Asakusa Frameworkのバッチは次のような構造を持ちます。

バッチの構造

名前

値

バッチ

バッチ全体

ジョブフロー

バッチ内のトランザクション単位

フェーズ

フロー内の処理内容の段階

ジョブ

フェーズ内の個々の実行単位

フェーズ

バッチの構成要素のうち、フェーズには以下のようなものがあります。

フェーズ一覧

名前

処理内容

setup

ジョブフローの実行環境をセットアップする 1

initialize

ジョブフローの処理内容を初期化する 2

import

ジョブフローの処理に必要なデータを外部システムからインポートする

prologue

インポートしたデータを本処理用に加工する

main

Hadoopジョブなどの本処理を行う

epilogue

本処理の結果をエクスポート用に加工する

export

ジョブフローの処理結果を外部システムにエクスポートする

finalize

ジョブフローの処理内容を完了またはロールバックさせる

cleanup

ジョブフローの実行環境をクリーンアップする

Attention

ジョブフローが途中で失敗した場合、 cleanup フェーズは実行されません。これは失敗した原因を分析するために、ジョブフローが出力した中間ファイルなどを保持しておくためです。

Note

上記の処理内容はあくまで概要で、これに即した処理が行われるとは限りません。

1

バージョン 0.10.3 時点では使用していません。

2

バージョン 0.10.3 時点では使用していません。

ジョブ

バッチの構成要素のうち、ジョブには以下のようなものがあります。

ジョブ一覧

名前

処理内容

Hadoopジョブ

HadoopのMapReduceジョブを実行する。1つのHadoopジョブで1つのMapReduceジョブ(ステージ)が実行される。

コマンドラインジョブ

Hadoopジョブ以外のジョブの総称。WindGateのインポート処理やエクスポート処理などを実行する。

バッチの構成要素間の関係

バッチの各要素は、以下の関係を持っています。

バッチは複数のジョブフローで構成され、 Batch DSL の定義にしたがった実行順序の依存関係を持つ

各ジョブフローは各フェーズを上から順に実行する (DSLの定義内容によっては、フェーズの一部がスキップされる)

各フェーズは複数のジョブで構成され、 Flow DSL の定義などにしたがった実行順序の依存関係を持つ

ジョブが実行する各処理は、 Flow DSL や Operator DSL の定義などによって決定される

以下は、上記の内容を俯瞰する図です。

プロファイルセット

YAESSはHadoopクラスターや複数の外部システムなどを組み合わせた複雑な環境上でAsakusa Frameworkのバッチを実行するために設計されています。 YAESSでは、それぞれの環境に対するジョブ起動方法の設定や、YAESSそのものの設定を「プロファイルセット」と呼んでいます。

このプロファイルセットは、 $ASAKUSA_HOME/yaess/conf/yaess.properties (以降「構成ファイル」)で管理されています。

構成ファイル

構成ファイル ( yaess.properties ) はJavaの一般的なプロパティファイルの文法で、主に下記のセクションから成り立っています。

プロパティファイルの項目

セクション

内容

core

YAESS本体の設定 (通常は変更しない)

hadoop

Hadoopジョブの実行 に関する設定

command

コマンドラインジョブの実行 に関する設定

scheduler

ジョブのスケジューリング に関する設定

lock

バッチ実行のロック に関する設定

monitor

バッチ実行のモニタ に関する設定

プロパティファイルのそれぞれのセクションには、該当するセクション名から始まるキーと、それに対応する値が記述されています。

yaess.properties

core = com.asakusafw.yaess.basic.BasicCoreProfile
core.version = 0.1

## file lock
lock = com.asakusafw.yaess.basic.BasicLockProvider
lock.scope = world
lock.directory = ${ASAKUSA_HOME}/yaess/var/lock

## ...

環境変数の利用

構成ファイルのいくつかの項目では、項目値の文字列に ${変数名} という形式を指定することで、YAESSを起動した環境の環境変数を含められます。

また、 ${変数名-デフォルト値} のように、 変数名の後に - を指定して、その後にデフォルト値を記述することで、 YAESSを起動した環境の環境変数が存在しない場合に、ここで指定したデフォルト値を設定することができます。

以下は、デフォルト値を持つ環境変数の利用例です。

yaess.properties

scheduler.parallel.hadoop-master = ${YAESS_PARALLEL_HADOOP-3}

YAESS本体の設定

YAESS本体の設定は、構成ファイル内の core セクション内に記述します。

YAESS本体の設定

名前

値

core

com.asakusafw.yaess.basic.BasicCoreProfile

core.version

0.1

上記の値は変更しないようにしてください。

Hadoopジョブの実行

Asakusa Frameworkで開発したバッチは、内部的にHadoopのジョブを投入してさまざまな処理を行っています。 YAESS上でHadoopに関する設定を行うには、構成ファイル内の hadoop セクションの内容を編集します。

同一環境上のHadoopジョブを実行する

YAESSを起動したコンピューターと同一のコンピューターにインストールされたHadoopを利用する場合、構成ファイルの hadoop セクションに以下の内容を設定します。

同一環境上のHadoopを実行する際の設定

名前

値

hadoop

com.asakusafw.yaess.basic.BasicHadoopScriptHandler

hadoop.env.HADOOP_CMD

hadoop コマンドのパス 3

hadoop.env.ASAKUSA_HOME

Asakusa Frameworkのインストール先

上記のうち、先頭の hadoop を除くすべての項目で 環境変数の利用 ができます。

3

この項目はオプションです。また、Hadoopのインストール先は別の設定方法もあります。詳しくは Hadoopを利用する際の環境変数の設定 を参照してください

SSHを経由してHadoopジョブを実行する

YAESSからSSHを経由してリモートコンピューター上のHadoopを利用する場合、構成ファイルの hadoop セクションに以下の内容を設定します。

SSHを経由してHadoopを実行する際の設定

名前

値

hadoop

com.asakusafw.yaess.jsch.SshHadoopScriptHandler

hadoop.ssh.user

ログイン先のユーザー名

hadoop.ssh.host

SSHのリモートホスト名

hadoop.ssh.port

SSHのリモートポート番号

hadoop.ssh.privateKey

ローカルの秘密鍵の位置

hadoop.ssh.passPhrase

秘密鍵のパスフレーズ

hadoop.env.HADOOP_CMD

リモートの hadoop コマンドのパス 4

hadoop.env.ASAKUSA_HOME

リモートのAsakusa Frameworkのインストール先

上記のうち、先頭の hadoop を除くすべての項目で 環境変数の利用 ができます。

なお、この仕組みではSSHでの通信に JSch 5 を利用しています。

4

この項目はオプションです。また、Hadoopのインストール先は別の設定方法もあります。詳しくは Hadoopを利用する際の環境変数の設定 を参照してください

5

http://www.jcraft.com/jsch/

Hadoopを利用する際の環境変数の設定

Hadoopを利用する際に特別な環境変数が必要な場合、以下の設定を追加します。

Hadoopを利用する際の環境変数の設定

名前

値

hadoop.env.<環境変数名>

設定する環境変数の値

ここで指定する値には 環境変数の利用 ができます。

Hint

hadoop.env.HADOOP_CMD や hadoop.env.ASAKUSA_HOME は上記の一部です。このうち、 ASAKUSA_HOME はAsakusa Frameworkの実行に必要であるため、常に指定するようにしてください。

HADOOP_CMD は代わりに HADOOP_HOME を指定することも可能です。詳しくは Hadoopコマンドの検索方法 を参照してください。

Tip

hadoop.env.<環境変数名>=${<環境変数名>} のように書くと、現在の環境変数を対象の環境にそのまま受け渡せます。

Hadoopコマンドの検索方法

Hadoopを起動する際には、起動する対象の hadoop コマンドの配置場所を環境変数を利用して指定する必要があります。 Hadoopのジョブや WindGate などを実行する際には、次の手順で hadoop コマンドを検索します。

環境変数 HADOOP_CMD が設定されている場合、 $HADOOP_CMD を hadoop コマンドとみなして利用します。

環境変数 HADOOP_HOME が設定されている場合、 $HADOOP_HOME/bin/hadoop コマンドを利用します。

hadoop コマンドのパス ( 環境変数 PATH ) が通っている場合、それを利用します。

上記の手順でHadoopコマンドが見つからない場合、対象処理の実行に失敗します。

Hadoopを利用する際のプロパティの設定

Hadoopを利用する際に特別なプロパティ 6 が必要な場合、以下の設定を追加します。

Hadoopを利用する際のプロパティの設定

名前

値

hadoop.prop.<プロパティ名>

設定するプロパティの値

ここで指定する値には 環境変数の利用 ができます。

6

Javaのシステムプロパティではなく、 hadoop コマンドに -D <key>=<value> で指定するプロパティです。

Hadoopブリッジの設定

同一環境上のHadoopジョブを実行する 場合や、 SSHを経由してHadoopジョブを実行する 場合には、Hadoopがインストールされた環境上に「Hadoopブリッジ」が必要です。

Hadoopブリッジは Asakusa Frameworkの $ASAKUSA_HOME/yaess-hadoop というディレクトリに含まれており、これにはYAESSがHadoopにジョブを投入する際に利用するツールが格納されています。

YAESSからHadoopを起動する際には、Hadoopが提供するコマンドを直接実行するのではなく、代わりに $ASAKUSA_HOME/yaess-hadoop/libexec/hadoop-execute.sh というシェルスクリプトを実行します。このシェルスクリプトは、最終的にHadoopのコマンドを実行するのですが、その手前でAsakusa Frameworkのための設定をいくつか行っています。

このシェルスクリプトの中では、 $ASAKUSA_HOME/yaess-hadoop/conf/env.sh というシェルスクリプトを内部的に実行しています。これは hadoop-execute.sh と同一プロセス内で実行され、ここで環境変数を設定するとHadoop実行時の環境変数を設定できます。

YAESSの構成ファイル側で設定しきれない環境変数等がある場合には、こちらで設定してください。

ジョブフロー中間ファイルのクリーンアップ

ジョブフローの実行が完了すると、その実行中に生成された中間ファイルは通常の場合に不要となります。以下の設定を行うことで、ジョブフローの完了時 7 にクリーンアップを行うかどうかを指定できます。

ジョブフローのクリーンアップの設定

名前

値

hadoop.cleanup

true でクリーンアップを行う、 false で行わない

hadoop.cleanup が未指定の場合、クリーンアップを行う( true が指定されたのと同じ )よう動作します。なおデフォルトの構成ファイルは hadoop.cleanup が未指定のため、クリーンアップが行われます。

7

実際には、これは cleanup フェーズ内で行われます。そのため、ジョブフローの途中で異常終了した場合には、クリーンアップは行われません。

Hadoopジョブ実行への介入

Hadoopのジョブを起動する際に、YAESSはHadoopがインストールされた環境の $ASAKUSA_HOME/yaess-hadoop/libexec/hadoop-execute.sh というシェルスクリプトを実行しています。このシェルスクリプトを実行する際に、以下の引数を指定しています。

Hadoopジョブ実行時の引数一覧

位置

内容

1

ジョブクライアントクラス名

2

バッチID

3

フローID

4

実行ID

5

バッチ実行引数 (文字列形式)

以降

その他のHadoopへの引数一覧

たとえば、ジョブクライアントクラス名が Client , バッチIDが bid , フローIDが fid , 実行IDが eid である場合、ジョブ実行時のコマンドは、以下のようになります。

$ASAKUSA_HOME/yaess-hadoop/libexec/hadoop-execute.sh Client bid fid eid

YAESSでは、このコマンドラインを構成するルールに対して、以下の設定で介入できます。

コマンドライン介入の設定 (Hadoopジョブ)

名前

値

hadoop.command.0

先頭に挿入されるトークン

hadoop.command.1

2番目に挿入されるトークン

hadoop.command.<n>

n + 1 番目に挿入されるトークン

つまり、 hadoop.command.0 に C:\\Cygwin\\bin\\bash.exe 8 , hadoop.command.1 に -r と指定した場合、先ほどの例は、以下のようになります。

C:\Cygwin\bin\bash.exe -r $ASAKUSA_HOME/yaess-hadoop/libexec/hadoop-execute.sh Client bid fid eid

また、それぞれの値には、 環境変数の利用 の形式で環境変数を、 @[位置] の形式で元のコマンドラインの指定位置(0起算)のトークンを利用できます。このとき、 @[0] は $ASAKUSA_HOME/yaess-hadoop/libexec/hadoop-execute.sh をさし、 @[1] はジョブクライアントクラス名をさし、といった具合になります。

8

*.properties ファイルではバックスラッシュ \ がエスケープ文字となるため、 \\ のように2つつなげて書く必要があります。

コマンドラインジョブの実行

WindGateなどのHadoop以外のジョブを、YAESSでは「コマンドラインジョブ」と総称しています。 YAESS上でコマンドラインジョブの設定を行うには、構成ファイル内の command セクションの内容を編集します。

コマンドラインジョブにはHadoopのジョブと異なり、「プロファイル」という概念があります。これは、それぞれのジョブが「どの環境で実行されるか」ということをあらわすもので、WindGateでは「プロファイル名」で指定したものが利用されます。

command セクションでは、プロファイルごとに command.<プロファイル名> という形式でサブセクションを作成し、その中にプロファイル固有の設定を記述することができます。

プロファイルの引き当て

command.<プロファイル名> というサブセクションを記載した場合、 <プロファイル名> の部分に指定した文字列と同じプロファイルを利用するコマンドラインジョブは、そのサブセクションの構成を利用して実行します。

プロファイルに対応するサブセクションが存在しない場合、そのコマンドラインジョブは command.* というサブセクションに記載した構成を利用して実行します。

例として、WindGateを利用する際にプロファイル名に asakusa を指定した場合、 command.asakusa というサブセクションで設定した内容が適用されます。そのサブセクションがない場合には、 command.* というサブセクションの内容が適用されます。

Attention

上記のいずれのサブセクションも存在しない場合、YAESSはエラーとなります。

同一環境上のコマンドラインジョブを実行する

YAESSを起動したコンピューターと同一のコンピューターでコマンドラインジョブを実行するには、構成ファイルの command.<プロファイル名> セクションに以下の内容を設定します。

同一環境上でコマンドラインを実行する際の設定

名前

値

command.<プロファイル名>

com.asakusafw.yaess.basic.BasicCommandScriptHandler

command.<プロファイル名>.env.HADOOP_CMD

hadoop コマンドのパス

command.<プロファイル名>.env.ASAKUSA_HOME

Asakusa Frameworkのインストール先

上記のうち、先頭の command.<プロファイル名> を除くすべての項目で 環境変数の利用 ができます。

Hint

command.<プロファイル名>.env.HADOOP_CMD の設定は必須ではありません。詳しくは コマンドラインジョブを実行する際の環境変数の設定 を参照してください。

SSHを経由してコマンドラインジョブを実行する

YAESSからSSHを経由し、リモートコンピューター上でコマンドラインジョブを実行するには、構成ファイルの command.<プロファイル名> セクションに以下の内容を設定します。

SSHを経由してコマンドラインを実行する際の設定

名前

値

command.<プロファイル名>

com.asakusafw.yaess.jsch.SshCommandScriptHandler

command.<プロファイル名>.ssh.user

ログイン先のユーザー名

command.<プロファイル名>.ssh.host

SSHのリモートホスト名

command.<プロファイル名>.ssh.port

SSHのリモートポート番号

command.<プロファイル名>.ssh.privateKey

ローカルの秘密鍵の位置

command.<プロファイル名>.ssh.passPhrase

秘密鍵のパスフレーズ

command.<プロファイル名>.env.HADOOP_CMD

リモートの hadoop コマンドのパス

command.<プロファイル名>.env.ASAKUSA_HOME

リモートのAsakusa Frameworkのインストール先

上記のうち、先頭の command.<プロファイル名> を除くすべての項目で 環境変数の利用 ができます。

なお、 SSHを経由してHadoopジョブを実行する 際と同様に、SSHでの通信に JSch を利用しています。

Hint

command.<プロファイル名>.env.HADOOP_CMD の設定は必須ではありません。詳しくは コマンドラインジョブを実行する際の環境変数の設定 を参照してください。

コマンドラインジョブを実行する際の環境変数の設定

コマンドラインジョブを実行する際に環境変数が必要な場合、以下の設定を追加します。

コマンドラインジョブを実行する際の環境変数の設定

名前

値

command.<プロファイル名>.env.<環境変数名>

設定する環境変数の値

ここで指定する値には 環境変数の利用 ができます。

Hint

command.<プロファイル名>.env.ASAKUSA_HOME などは上記の一部です。ただし、環境変数 ASAKUSA_HOME はコマンドラインジョブの実行に必要であるため、常に指定するようにしてください。

また、Asakusa Frameworkが提供するほとんどのコマンドは hadoop コマンドを内部で利用しているため、上記で環境変数 HADOOP_CMD などを明示的に設定しておくことを推奨します。 Hadoopの位置を知らせる方法は環境変数 HADOOP_CMD を設定する代わりに HADOOP_HOME や PATH に適切な値を指定するなどがあります。

詳しくは Hadoopコマンドの検索方法 を参照してください。

Tip

command.<プロファイル名>.env.<環境変数名>=${<環境変数名>} のように書くと、現在の環境変数を対象の環境にそのまま受け渡せます。

コマンドラインジョブ実行への介入

YAESSがコマンドラインジョブを実行する際には、そのジョブのコマンドラインを指定の環境上で直接実行しています 9 。このコマンドラインに対して、以下の設定で介入できます。

コマンドライン介入の設定 (コマンドラインジョブ)

名前

値

command.<プロファイル名>.command.0

先頭に挿入されるトークン

command.<プロファイル名>.command.1

2番目に挿入されるトークン

command.<プロファイル名>.command.<n>

n + 1 番目に挿入されるトークン

たとえば、もとのコマンドラインが /bin/echo , hello で、 command.<プロファイル名>.command.0 に C:\\Cygwin\\bin\\bash.exe , command.<プロファイル名>.command.1 に -r と指定した場合、実際に実行されるコマンドは以下のようになります。

C:\Cygwin\bin\bash.exe -r /bin/echo hello

また、それぞれの値には、 環境変数の利用 の形式で環境変数を、 @[位置] の形式で元のコマンドラインの指定位置(0起算)のトークンを利用できます。このとき、 @[0] はコマンドラインの実行可能ファイルパスをさし、 @[1] はコマンドラインの最初の引数といった具合になります。

9

より詳しく言えば、環境上のコマンドラインシェルに、ジョブのコマンドラインをそのまま渡してプロセスを起動します。

ジョブのスケジューリング

YAESSはバッチを実行する際、バッチが構成するジョブの実行順序等を、構成ファイルの schedule セクションで指定できます。

ジョブのスケジューリングを説明するために、 Asakusa Frameworkのバッチ構造 で説明したバッチ構造の俯瞰図を再掲します。

上図では、バッチは3つのジョブフローから構成されています。 1つめのジョブフローの終了後に実行される2つのジョブフローは依存関係がないため、並列で実行することが可能な構造を持っています。また、 import フェーズは2つのジョブから構成されていますが、これらも依存関係がないため、並列で実行することが可能です。 main フェーズについても一部で並列で実行可能な箇所が存在します。

ジョブのスケジューリングはこのような構造を持つバッチに対して、ジョブ実行時にどのような実行順序で実行するかを設定します。

もっとも単純なスケジューリング

もっとも単純なジョブのスケジューリングでは、それぞれのジョブを依存関係の順に1つずつ実行します。構成ファイルの schedule セクションに以下の内容を指定します。

単純なジョブのスケジューリングを行う際の設定

名前

値

scheduler

com.asakusafw.yaess.basic.BasicJobScheduler

ジョブを並列実行する際のスケジューリング

依存関係を考慮しながら複数のジョブを同時に実行する場合、構成ファイルの schedule セクションに以下の内容を指定します。

ジョブを並列実行する際の設定

名前

値

scheduler

com.asakusafw.yaess.paralleljob.ParallelJobScheduler

scheduler.parallel.default

同時に実行可能なジョブの個数

ジョブの種類ごとに同時に動作させるジョブの個数を設定することも可能です。

YAESSでは、スケジュールを指定するジョブを「リソース」という単位で識別します。各種ジョブの定義にリソースを示すプロパティを追加しておき、スケジュールの設定では、そのリソースに対して同時に実行するジョブの個数などのスケジュール設定を行います。

リソース単位でスケジュール設定の指定を行う場合、構成ファイルに以下の内容を追加します。

種類ごとにジョブを並列実行する際の設定

名前

値

hadoop.resource

Hadoopジョブ 10 のリソース名

command.<プロファイル名>.resource

コマンドラインジョブ 11 のリソース名

scheduler.parallel.<リソース名>

指定のリソース名のジョブに対する同時実行可能な数

上記の指定により、たとえばHadoopジョブの並列度を1に設定しながら、WindGateのジョブの並列度を3に設定する、などが可能です。

なお、リソース名に対して scheduler.parallel.<リソース名> の指定が存在しない場合、代わりに scheduler.parallel.default の設定を利用します。

Attention

つまり、 default という名前のリソース名はYAESS内で特別扱いされています。通常はこの名前をリソース名に使用しないでください。

Hint

上記ではHadoopジョブの実行とコマンドラインジョブの実行にそれぞれリソースを1つずつ割り当てる設定方法を説明していますが、 ジョブ実行クラスターの振り分け で説明する asakusa-yaess-multidispatch を使うことで、例えばHadoopジョブの実行の中で複数のリソースを設定し、それぞれ個別のスケジュール設定を行う、といった使い方も可能になっています。

10

Hadoopジョブの実行 を参照

11

コマンドラインジョブの実行 を参照

バッチ実行のロック

YAESSではバッチを実行する際に、ほかのバッチの実行を抑制するロックの仕組みが用意されています。 YAESS上でHadoopに関する設定を行うには、構成ファイル内の lock セクションの内容を編集します。

Note

現在のYAESSには、 同一環境上のバッチ実行を抑制するロック のみが用意されています。

同一環境上のバッチ実行を抑制するロック

YAESSを実行中のコンピューターで、ほかのYAESSの実行を抑制するには、構成ファイルの lock セクションに以下の内容を指定します。

同一環境上のバッチ実行を抑制する際の設定

名前

値

lock

com.asakusafw.yaess.basic.BasicLockProvider

lock.directory

ロックファイルの保存先パス

上記のうち、 lock.directory には 環境変数の利用 ができます。

ロックのスコープ

ロックには実行を抑制する範囲を表す「スコープ」を指定できます。これには、構成ファイルの lock セクションに以下の内容を追加します。

ロックのスコープを指定する際の設定

名前

値

lock.scope

スコープの種類

スコープの種類には以下のものがあります。

ロックスコープの種類

スコープ

値

world

バッチ実行中は他の任意のバッチを同時に実行しない

batch

同じバッチを同時に2つ以上実行しない

flow

同じジョブフローを同時に2つ以上実行しない

execution

同じ実行IDのジョブフローを同時に2つ以上実行しない

なお、スコープの指定がない場合、 execution が指定された場合と同様の動きをします。

バッチ実行のモニタ

YAESSには、実行中のバッチの進捗状況を監視したり、またはその実行をキャンセルしたりするためのモニターの機能が提供されています。このモニタに関する設定を行うには、構成ファイル内の monitor セクションの内容を編集します。

進捗ログを出力するモニタ

バッチ内のそれぞれのフェーズの進捗状況をログに出力するには、構成ファイルの monitor セクションに以下の内容を設定します。

進捗ログを出力するモニタを利用する際の設定

名前

値

monitor

com.asakusafw.yaess.basic.BasicMonitorProvider

monitor.stepUnit

ログを出力する進捗の単位 (0.0 ~ 1.0)

monitor.stepUnit は、フェーズの進捗度が変化した際に、ログに出力する単位です。この値は0以上1以下で指定し、進捗度が指定された単位を超えた際にログに状態を出力します (0が指定された場合にはログを出力しません)。たとえば、この値に 0.05 と指定した場合、進捗ログは最低でも5%単位になります。

このモニタは、YAESS本体のログ設定を利用してログを出力しています。 YAESS本体のログ設定は YAESSのログ設定 を参照してください。

ジョブフローごとに進捗状況を個別ファイルに出力するモニタ

バッチ内のそれぞれのジョブフローの進捗状況を個別のファイルに出力するには、 asakusa-yaess-flowlog プラグインを利用します。プラグインについては プラグインライブラリの管理 を参照してください。

このモニタを利用するには、構成ファイルの monitor セクションに以下の内容を設定します。

ジョブフローごとに進捗状況を個別ファイルに出力する際の設定

名前

既定値

値

monitor

(なし)

com.asakusafw.yaess.flowlog.FlowLoggerProvider

monitor.directory

(なし)

ファイルの出力先ディレクトリ

monitor.encoding

UTF-8

ファイル出力時のエンコーディング

monitor.stepUnit

0.0

ログを出力する進捗の単位 (0.0 ~ 1.0)

monitor.dateFormat

yyyy-MM-dd HH:mm:ss

時刻の形式

monitor.reportJob

true

ジョブの進捗状況もファイルに出力する

monitor.deleteOnSetup

true

ジョブフロー開始時にファイルを削除する

monitor.deleteOnCleanup

true

ジョブフロー正常終了時にファイルを削除する

monitor.directory は、出力先のディレクトリです。 <出力先ディレクトリ>/<バッチID>/logs/<フローID> というファイルに進捗状況を書き出します。

monitor.stepUnit は、フェーズの進捗度が変化した際にファイルに途中経過を出力する単位です。進捗ログを出力するモニタ と同様の設定を行えます。

monitor.dateFormat は SimpleDateFormat 12 と同様の形式を指定します。ここで指定された日時の形式を利用してファイルにそれぞれの状況を記録します。

monitor.reportJob は true または false の形式で指定します。 false が指定された場合には、ジョブフロー内のそれぞれのフェーズに関する進捗状況がファイルに記録されます。 true が指定された場合にはさらにそれぞれのジョブの開始と終了も併せてファイルに記録されます。ただし、ジョブ内で発生したエラーはいずれの設定でも記録されます。

monitor.deleteOnSetup は true または false の形式で指定します。 true が指定された場合には setup フェーズ開始直前に対応する進捗状況のファイルを削除します。 false が指定された場合には setup フェーズ開始時にファイルを削除せず、追記モードでファイルを開きます。

monitor.deleteOnCleanup は true または false の形式で指定します。 true が指定された場合には cleanup フェーズ正常終了時に進捗状況のファイルを削除します。 false が指定された場合には cleanup フェーズ正常終了時にファイルを <出力先ディレクトリ>/<バッチID>/cleanup/<フローID> に移動します。

上記のうち、 monitor.directory には 環境変数の利用 ができます。

Hint

cleanup フェーズはジョブフローが途中で失敗した際には実行されません。そのため、ジョブフロー内で任意のエラーが発生した場合、設定によらず <出力先ディレクトリ>/<バッチID>/logs/<フローID> というファイルが残った状態になります。それぞれのジョブフローがどこまで進んだかを把握したい場合、このモニタが有効です。

Hint

進捗ログを出力するモニタ とは異なり、上記のモニタはYAESS本体のログ設定に影響されません。

それぞれの進捗状況は <日時> [<レベル>:<コード>] <メッセージ>... の形式でファイル内に記載されます。 <レベル> は 情報レベルを表す INFO , 警告レベルを表す WARN , エラーレベルを表す ERROR のいずれかで、 <コード> は状況に応じて以下のいずれかを利用します。

ジョブフローごとに進捗状況を個別ファイルに出力するモニタのログコード

コード

概要

START-<フェーズ名>-PHASE

<フェーズ名> のフェーズが開始した

STEP-<フェーズ名>-PHASE

<フェーズ名> のフェーズが一定以上進捗した

FINISH-<フェーズ名>-PHASE

<フェーズ名> のフェーズが終了した

START-<フェーズ名>-JOB

<フェーズ名> 内でジョブが開始した

FINISH-<フェーズ名>-JOB

<フェーズ名> 内でジョブが終了した

それぞれのフェーズについて詳しくは ジョブのスケジューリング を参照してください。

12

java.text.SimpleDateFormat

その他のYAESSの設定

構成ファイルのほかにも、いくつかYAESSの実行に関する設定があります。

YAESSの環境変数設定

YAESSの実行に特別な環境変数を利用する場合、 $ASAKUSA_HOME/yaess/conf/env.sh 内でエクスポートして定義できます。

YAESSを利用する場合、以下の環境変数が必要です。

YAESSの実行に必要な環境変数

名前

備考

ASAKUSA_HOME

Asakusaのインストール先パス。

特別な理由がない限り、 ASAKUSA_HOME はYAESSを実行する前にあらかじめ定義しておいてください。 $ASAKUSA_HOME/yaess/conf/env.sh では、その他必要な環境変数を定義するようにしてください。

また、特別な環境変数として以下を利用できます。

YAESSで利用可能な環境変数

名前

備考

YAESS_OPTS

YAESSを実行するJava VMの追加オプション。

YAESSのログ設定

YAESSは内部のログ表示に SLF4J 13 、およびバックエンドに Logback 14 を利用しています。ログの設定を変更するには、 $ASAKUSA_HOME/yaess/conf/logback.xml を編集してください。

また、YAESSの実行時には以下の値がシステムプロパティとして設定されます。

YAESS実行時のシステムプロパティ

名前

値

com.asakusafw.yaess.log.batchId

バッチID

Logback以外のログの仕組みを利用する場合、 $ASAKUSA_HOME/yaess/lib にあるLogback関連のライブラリを置換した上で、設定ファイルを $ASAKUSA_HOME/yaess/conf などに配置します (ここは実行時にクラスパスとして設定されます)。

Attention

YAESSから起動されるHadoopや、WindGateなどは、それぞれのログ設定を利用します。ここでの設定は、あくまでYAESS本体のみのものです。

13

http://www.slf4j.org/

14

http://logback.qos.ch/

プラグインライブラリの管理

YAESSのいくつかの機能を利用するには、追加のプラグインライブラリが必要になる場合があります。そのような機能を利用する場合、必要なライブラリを $ASAKUSA_HOME/yaess/plugin ディレクトリ直下に配置してください。

標準的なプラグインはYAESS導入時に自動的にプラグインが追加されますが、その他のプラグインは拡張モジュールとして提供されるため、必要に応じて拡張モジュールを導入してください。

See also

拡張モジュールの一覧やその導入方法については、 Asakusa Gradle Plugin ユーザーガイド や Asakusa Framework デプロイメントガイド を参照してください。

標準プラグインライブラリ

Asakusa Frameworkのデプロイメントアーカイブには、デフォルトのYAESS用プラグインライブラリとして、あらかじめ以下のプラグインライブラリと、プラグインライブラリが使用する依存ライブラリが同梱されています。

YAESS標準プラグインライブラリ

プラグインライブラリ

説明

asakusa-yaess-paralleljob

ジョブを並列実行のためのプラグイン

asakusa-yaess-jsch

SSH経由でジョブを起動するためのプラグイン

jsch

asakusa-yaess-jsch が依存するSSH接続用ライブラリ

asakusa-yaess-flowlog

ジョブフローごとに進捗状況を個別ファイルに出力するためのプラグイン

asakusa-yaess-multidispatch

ジョブの実行クラスターの振り分けを行うためのプラグイン

YAESSによるバッチの実行

YAESSの プロファイルセット を作成し終えたら、それを利用してバッチアプリケーションを実行します。

バッチアプリケーションのデプロイ

YAESSを利用してバッチアプリケーションを実行する場合、YAESSを実行する環境上に同アプリケーションをデプロイする必要があります。

See also

運用環境のデプロイメントに関しては、 Asakusa Framework デプロイメントガイド を参照してください。

実行計画の確認

バッチアプリケーション用のデプロイメントアーカイブには、バッチアプリケーション毎にYAESS用のワークフロー記述としてYAESSスクリプト ( <バッチID>/etc/yaess-script.properties )というファイルが含まれます。 YAESSはYAESSスクリプトの定義内容に基づいてバッチアプリケーションを実行します。

YAESSスクリプトはバッチ全体のワークフローの構造をYAESS向けに表しています。 YAESSスクリプトの内容を確認するには、コマンドラインから $ASAKUSA_HOME/yaess/bin/yaess-explain.sh <YAESSスクリプトのパス> と入力します。

なお、YAESSスクリプトのパスは、通常 $ASAKUSA_HOME/batchapps/<バッチID>/etc/yaess-script.properties です。また、アプリケーションの配置前であれば、 <コンパイラの出力先ディレクトリ>/<バッチID>/etc/yaess-script.properties を指定してください。

このコマンドは、バッチの構造をフェーズの単位まで分解して、JSON形式で表示します。通常、バッチは複数のジョブフローと、さらに複数のフェーズから構成されています。

以下はコマンドの出力結果の例です。

yaess-script.properties

{
  "id": "example.summarizeSales",
  "jobflows": [
    {
      "id": "byCategory",
      "blockers": [],
      "phases": [
        "setup",
        "import",
        "main",
        "epilogue",
        "export",
        "finalize",
        "cleanup"
      ]
    }
  ]
}

JSONオブジェクトのトップレベルはバッチ全体を表していて、以下のような構造になっています。

実行計画の構造 (バッチ)

名前

値

id

バッチID

jobflows

バッチ内のジョブフローの一覧

また、それぞれのジョブフロー ( jobflows ) は以下のような構造になっています。

実行計画の構造 (ジョブフロー)

名前

値

id

フローID

blockers

このジョブフローの実行の前提となるジョブフローのID一覧

phases

このジョブフローに含まれるフェーズ一覧。

バッチ全体の実行

バッチアプリケーション全体を実行するには、コマンドラインから $ASAKUSA_HOME/yaess/bin/yaess-batch.sh <バッチID> と入力します。また、バッチに起動引数を指定する場合、コマンドラインの末尾に -A <変数名>=<値> のように記述します。

$ASAKUSA_HOME/yaess/bin/yaess-batch.sh example.summarizeSales -A date=2011-04-01

出力の最後に Finished: SUCCESS と表示されればバッチ処理は成功です。なお、バッチ処理の結果はコマンドの終了コードでも確認できます。 YAESSではUnixの方式に従い、正常終了の場合は 0 , それ以外の場合は 0 でない終了コードを返します。

Starting YAESS
     Profile: /home/asakusa/asakusa/yaess/conf/yaess.properties
      Script: /home/asakusa/asakusa/batchapps/example.summarizeSales/etc/yaess-script.properties
    Batch ID: example.summarizeSales
...

Finished: SUCCESS

なお、各ジョブフローの initialize フェーズから finalize フェーズまでに例外が発生した場合、YAESSは即座に finalize フェーズの実行を試みた後、バッチの実行を異常終了させます。 finalize フェーズではアプリケーションが不安定にならないようにロールバックなどの処理が行われますが、ここでも失敗した場合には フェーズ単位の実行 で finalize フェーズを個別に実行する必要があります。

ジョブフローのスキップ

バッチに含まれる一部のジョブフローの実行を省略してバッチを実行したい場合、コマンドライン引数の末尾に -D skipFlows=<フローID> のように、省略したいジョブフローのフローIDを指定します。複数のジョブフローを省略する場合、カンマ区切りで -D skipFlows=<フローID>,<フローID>,... のようにそれぞれ指定します。

以下はコマンドラインの例です。バッチ ex 全体を実行しますが、ジョブフロー first と second の実行を省略します。

$ASAKUSA_HOME/yaess/bin/yaess-batch.sh ex -A code=123 -D skipFlows=first,second

Hint

上記の機能は、バッチの途中で一部のジョブフローの処理が失敗した際に、途中からバッチを実行する際に利用できます。

ジョブフロー単位の実行

バッチをジョブフロー単位で部分的に実行するには、コマンドラインから $ASAKUSA_HOME/yaess/bin/yaess-flow.sh <バッチID> <フローID> <実行ID> と入力します。また、 バッチ全体の実行 と同様に、 -A <変数名>=<値> という形式で引数をいくつも指定できます。

それぞれの値は次のような意味を持ちます。

バッチID

バッチのID。 Asakusa DSL内で @Batch(name = "...") 15 として指定した名前を利用する。

フローID

ジョブフローのID。 Asakusa DSL内で @JobFlow(name = "...") 16 として指定した名前を利用する。

実行ID

ジョブフローの実行ごとのID。ワーキングディレクトリの特定や、ロングランニングトランザクションのIDとして利用する。同じジョブフローのそれぞれのフェーズで同じものを利用する必要があるが、同じジョブフローでも実行のたびに異なるものを指定する必要がある。

上記のうち実行IDを除いては、 実行計画の確認 のものと同様です。

15

com.asakusafw.vocabulary.batch.Batch [https://docs.asakusafw.com/0.10.3/release/api/com/asakusafw/vocabulary/batch/Batch.html]

16

com.asakusafw.vocabulary.flow.JobFlow [https://docs.asakusafw.com/0.10.3/release/api/com/asakusafw/vocabulary/flow/JobFlow.html]

フェーズ単位の実行

バッチをフェーズ単位で部分的に実行するには、コマンドラインから $ASAKUSA_HOME/yaess/bin/yaess-phase.sh <バッチID> <フローID> <フェーズ名> <実行ID> と入力します。また、 バッチ全体の実行 と同様に、 -A <変数名>=<値> という形式で引数をいくつも指定できます。

それぞれの値は次のような意味を持ちます。

バッチID

バッチのID。 Asakusa DSL内で @Batch(name = "...") として指定した名前を利用する。

フローID

ジョブフローのID。 Asakusa DSL内で @JobFlow(name = "...") として指定した名前を利用する。

フェーズ名

ジョブフロー内のフェーズ名 17 。

実行ID

ジョブフローの実行ごとのID。ワーキングディレクトリの特定や、ロングランニングトランザクションのIDとして利用する。同じジョブフローのそれぞれのフェーズで同じものを利用する必要があるが、同じジョブフローでも実行のたびに異なるものを指定する必要がある。

上記のうち実行IDを除いては、 実行計画の確認 のものと同様です。

Attention

フェーズ単位でバッチを実行する場合、 同一環境上のバッチ実行を抑制するロック が実行のたびに取得され、実行終了時に開放されます。実行と実行の間にほかのバッチに割り込まれてしまう可能性がありますので、これより上位の仕組みでの排他制御が必要になるかもしれません。

Hint

フェーズ単位の実行 機能は、ほかのジョブ管理システムとの連携を企図しています。そのため、バッチ全体を手動で実行する場合には、基本的に バッチ全体の実行 を行ってください。

17

yaess-phase.sh で指定できるフェーズは1つのみです。複数のフェーズを部分的に実行したい場合は、 yaess-phase.sh に異なるフェーズを指定して複数回実行してください。

その他の実行に関する機能

シミュレーションモード

実際の処理を実行せず、環境構成や設定の確認のみを行いたい場合、コマンドライン引数の末尾に -D dryRun と指定します。

以下はコマンドラインの例です。

$ASAKUSA_HOME/yaess/bin/yaess-batch.sh ex -A code=123 -D dryRun

シミュレーションモードでは、HadoopやWindGateをシミュレーションモードで実行します。シミュレーションモードの動作はそれぞれ異なりますが、基本的には設定や引数を確認した後、データの入出力を行わずに終了します。

Attention

引数 -D dryRun は -D dryRun=true の省略記法です。いずれの場合でも、 -D と dryRun は離して入力してください。

アプリケーションの検証

バッチアプリケーションをYAESSで実行すると、HadoopやWindGateなどそれぞれの環境においてアプリケーションライブラリの検証を行います。

以下の内容についての検証が行われます。

YAESSを起動した際のアプリケーションと、各環境で実行しようとしているアプリケーションのライブラリが一致するか

各環境で実行しようとしているアプリケーションと、その環境にインストールされたランタイムライブラリのバージョンが一致するか

Tip

アプリケーションの検証では、ジョブフローのJARファイルに含まれる META-INF/asakusa/application.properties というファイルの情報を利用します。

アプリケーションの検証に失敗した場合、 InconsistentApplicationException 18 という例外がスローされてプログラムが終了します。

上記の検証を利用しない場合、コマンドライン引数の末尾に -D verifyApplication=false と指定します。上記の指定がない場合、常にアプリケーションの検証を行います。

Attention

アプリケーションの検証は常に有効にしておくことを強く推奨します。現在のAsakusa Frameworkでは、同一のAsakusa DSLのソースコードに対してもバッチコンパイルの結果生成されるバッチアプリケーションの実行計画は不定です。実行計画が異なるアプリケーションを異なる環境に配置して実行した場合、予期しない動作をする可能性が高いです。

18

com.asakusafw.runtime.core.context.InconsistentApplicationException [https://docs.asakusafw.com/0.10.3/release/api/com/asakusafw/runtime/core/context/InconsistentApplicationException.html]

プロファイルセットの指定

コマンドラインの引数に -D profile=<プロファイル名> と指定することで、$ASAKUSA_HOME/yaess/conf/ 配下に配置した任意の構成ファイルを使用することができます。

以下は、 $ASAKUSA_HOME/yaess/conf/custom-profile.properties という構成ファイルを使ってバッチを実行する例です。

$ASAKUSA_HOME/yaess/bin/yaess-batch.sh ex -A code=123 -D profile=custom-profile

このオプションを指定しない場合、 $ASAKUSA_HOME/yaess/conf/yaess.properties が標準の構成ファイルとして使用されます。

環境変数の指定

コマンドラインの引数に -V <key>=<value> と指定することで、コマンドライン経由で環境変数を指定することができます。

この機能は、プロファイルセットで 環境変数の利用 を使って定義した項目値に対して、コマンドライン経由でその値を設定するといった場合に利用します。

例えば、 プロファイルセット内で、Hadoopジョブの並列度を scheduler.parallel.hadoop-master = ${YAESS_PARALLEL_HADOOP} のように設定した場合、コマンドラインからこの値を指定するには以下のように実行します。

$ASAKUSA_HOME/yaess/bin/yaess-batch.sh ex -A code=123 -V YAESS_PARALLEL_HADOOP=4

実行結果の確認

YAESSの実行結果を確認するには YAESSのログ設定 で設定した内容に基づいて出力されたログを確認します。

YAESSのログ内容については、 YAESSに関するログ一覧 も参照してください。

また、YAESSのログの概要を把握するためのツールとして、YAESS Log Analyzerツールが提供されています。詳しくは、 YAESSログの可視化 を参照してください。

ジョブ実行クラスターの振り分け

この文書では、ジョブの実行クラスターの振り分けを行うYAESSプラグイン asakusa-yaess-multidispatch の利用方法について解説します。

このプラグインを利用すると、個々のバッチやジョブフローなどを異なるクラスター上に振り分けて実行したり、それぞれ異なる設定で起動したりできるようになります。

クラスターの振り分け方法

このプラグインでは、バッチに含まれるそれぞれのジョブを実行する際に、それぞれ異なる設定を使ったジョブの実行が行えます。バッチごとに異なる設定のクラスター上で処理を行ったり、ジョブフローごとに異なるHadoopパラメーターを利用するなど様々な設定が可能です。

このプラグインを利用する場合、YAESS本体の構成ファイルの hadoop セクション 1 や command.<プロファイル名> セクション 2 に、専用のハンドラを登録します。また、ハンドラの設定の中に、振り分け先のクラスター上でジョブを実行するような別のハンドラを複数登録します。ここでは、このプラグインが提供するハンドラを「振り分けハンドラ」、振り分け先のハンドラのことを「サブハンドラ」と呼びます。

構成ファイルについての詳しい情報は、 Hadoopジョブの振り分け設定 や コマンドラインジョブの振り分け設定 をそれぞれ参照してください。

振り分ける規則は、「振り分け設定ファイル」というファイルを作成し、その中に記述します。このファイルは対象のバッチごとに <バッチID>.properties というプロパティファイルとして作成します。

振り分け設定ファイル内には、ジョブフロー、フェーズ、ジョブがそれぞれどのサブハンドラを利用してジョブを起動するかを記載します。振り分けハンドラは、振り分け設定ファイル内の情報をもとに、適切なサブハンドラを選択してそれぞれのジョブを実行します。

振り分け設定ファイルについての詳しい情報は、 ジョブの振り分け先設定 を参照してください。

1

hadoop セクションについては YAESSユーザーガイド - Hadoopジョブの実行 を参照してください。

2

command セクションについては YAESSユーザーガイド - コマンドラインジョブの実行 を参照してください。

プラグインの利用方法

プラグインの登録

このプラグインを利用するには、 asakusa-yaess-multidispatch というプラグインライブラリをYAESSに登録します。このプラグインは バージョン 0.10.3 ではYAESSの標準構成に含まれています。

Hadoopジョブの振り分け設定

Hadoopジョブをサブハンドラに振り分けて実行する場合、構成ファイルの hadoop セクションに以下の内容を設定します。

Hadoopジョブの振り分け設定

名前

値

hadoop

com.asakusafw.yaess.multidispatch.HadoopScriptHandlerDispatcher

hadoop.conf.directory

振り分け設定ファイルを配置するディレクトリ

hadoop.conf.setup

setup フェーズを実行するサブハンドラ名

hadoop.conf.cleanup

cleanup フェーズを実行するサブハンドラ名

hadoop.<サブハンドラ名>

サブハンドラのクラス名

hadoop.<サブハンドラ名>.<設定名>

サブハンドラの設定値

hadoop には振り分けハンドラを利用するためのディスパッチャクラスを指定します。 YAESS導入時には hadoop には標準的なハンドラクラスが設定されているので、この設定を変更します。

hadoop.conf.directory は振り分け設定ファイルを配置するディレクトリへの絶対パスを指定します。このディレクトリの直下に対象バッチのバッチIDと同名の振り分け設定ファイルを作成し、それぞれのファイルで ジョブの振り分け先設定 を行います。

hadoop.conf.setup と hadoop.conf.cleanup はいずれも省略可能です。省略した場合は振り分け設定ファイルの内容を元にサブハンドラを選択します。上記にサブハンドラ名を設定した場合、振り分け設定ファイルの内容によらず指定のサブハンドラで setup フェーズや cleanup フェーズのジョブをそれぞれ実行します。

hadoop.<サブハンドラ名> や hadoop.<サブハンドラ名>.<設定名> では、サブハンドラの設定を行います。ここでは、通常の hadoop セクションの代わりに hadoop.<サブハンドラ名> というサブセクションを作成し、それぞれのサブハンドラの設定を行ってください。サブハンドラ名には半角の英数字のみを利用してください。

例えば、サブハンドラ名に remote を指定し、このハンドラに対して SSHを経由してHadoopジョブを実行する 設定を適用する場合、以下例のようになります 3 。

yaess.properties

hadoop.remote = com.asakusafw.yaess.jsch.SshHadoopScriptHandler
hadoop.remote.ssh.user=asakusa
hadoop.remote.ssh.host=example.com
hadoop.remote.ssh.port=22

サブハンドラは複数定義することが出来ますが、必ず default という名前のサブハンドラの設定を含めてください。これは、振り分け設定ファイルで振り分け先のサブハンドラが明示的に指定されなかった場合に利用されるサブハンドラとなります。

Attention

default という名前のサブハンドラが設定されていない場合、YAESSの初期化時にエラーとなります。

上記のうち、先頭の hadoop を除くすべての項目には ${変数名} という形式で、YAESSを起動した環境の環境変数を含められます。ただし、サブハンドラについてはサブハンドラごとの設定項目によって環境変数を利用可能かどうかが決まります。

3

ここでは設定の一部のみを記載しています。サブハンドラの設定については後述の 設定例 も参考にしてください。

コマンドラインジョブの振り分け設定

コマンドラインジョブをサブハンドラに振り分けて実行する場合、構成ファイルの command.<プロファイル名> セクションに以下の内容を設定します。

コマンドラインジョブの振り分け設定

名前

値

command.<プロファイル名>

com.asakusafw.yaess.multidispatch.CommandScriptHandlerDispatcher

command.<プロファイル名>.conf.directory

振り分け設定ファイルを配置するディレクトリ

command.<プロファイル名>.conf.setup

setup フェーズを実行するサブハンドラ名

command.<プロファイル名>.conf.cleanup

cleanup フェーズを実行するサブハンドラ名

command.<プロファイル名>.<サブハンドラ名>

サブハンドラのクラス名

command.<プロファイル名>.<サブハンドラ名>.<設定名>

サブハンドラの設定値

command.<プロファイル名> には振り分けハンドラを利用するためのディスパッチャクラスを指定します。 YAESS導入時には command.<プロファイル名> には標準的なハンドラクラスが設定されているので、この設定を変更します。

command.<プロファイル名>.conf.directory は振り分け設定ファイルを配置するディレクトリへの絶対パスを指定します。このディレクトリの直下に対象バッチのバッチIDと同名の振り分け設定ファイルを作成し、それぞれのファイルで ジョブの振り分け先設定 を行います。

command.<プロファイル名>.conf.setup と command.<プロファイル名>.conf.cleanup はいずれも省略可能です。省略した場合は振り分け設定ファイルの内容を元にサブハンドラを選択します。上記にサブハンドラ名を設定した場合、振り分け設定ファイルの内容によらず指定のサブハンドラで setup フェーズや cleanup フェーズのジョブをそれぞれ実行します。

command.<プロファイル名>.<サブハンドラ名> や command.<プロファイル名>.<サブハンドラ名>.<設定名> では、サブハンドラの設定を行います。ここでは、通常の command.<プロファイル名> セクションの代わりに command.<プロファイル名>.<サブハンドラ名> というサブセクションを作成し、それぞれのサブハンドラの設定を行ってください。サブハンドラ名には半角の英数字のみを利用してください。

例えば、サブハンドラ名に remote を指定し、このハンドラに対してコマンドラインジョブのプロファイル asakusa に対して SSHを経由してコマンドラインジョブを実行する 設定を適用する場合、以下のようになります 4 。

yaess.properties

command.asakusa.remote = com.asakusafw.yaess.jsch.SshCommandScriptHandler
command.asakusa.remote.ssh.user=asakusa
command.asakusa.remote.ssh.host=example.com
command.asakusa.remote.ssh.port=22

Attention

コマンドラインジョブの振り分け機能を使うと、 コマンドラインジョブの実行 で説明するプロファイル単位で実行方法を切り替える機能の代替として、単一のプロファイル( command.* )のみを指定し、ジョブフロー単位でコマンドラインジョブを振り分けることで同様の振る舞いを実現可能な場合がありますが、この方法は推奨できません。

プロファイル単位で実行方法を分ける必要がある場合は、できるだけプロファイル名を分けて個別の command.<プロファイル名> セクションを用意して設定を切り替えるべきです。

サブハンドラは複数定義することが出来ますが、必ず default という名前のサブハンドラの設定を含めてください。これは、振り分け設定ファイルで振り分け先のサブハンドラが明示的に指定されなかった場合に利用されるサブハンドラとなります。

Attention

default という名前のサブハンドラが設定されていない場合、YAESSの初期化時にエラーとなります。

上記のうち、先頭の command.<プロファイル名> を除くすべての項目には ${変数名} という形式で、YAESSを起動した環境の環境変数を含められます。ただし、サブハンドラについてはサブハンドラごとの設定項目によって環境変数を利用可能かどうかが決まります。

4

ここでは設定の一部のみを記載しています。サブハンドラの設定については後述の 設定例 も参考にしてください。

ジョブの振り分け先設定

ジョブをサブハンドラに振り分ける際には、「振り分け設定ファイル」を利用して振り分け先を判断します。

この振り分け設定ファイルは、 hadoop.conf.directory や command.<プロファイル名>.conf.directory で指定したディレクトリの直下に <バッチID>.properties という名前で作成します 5 。

振り分け設定ファイルには、以下のような行をJavaのプロパティファイルの形式で記載します。

ジョブの振り分け先設定

優先順位

行の内容

概要

1

<フローID>.<フェーズ名>.<ステージID> = <サブハンドラ名>

対象のジョブを指定のサブハンドラで実行する

2

<フローID>.<フェーズ名>.* = <サブハンドラ名>

対象フェーズ 6 のすべてのジョブを指定のサブハンドラで実行する

3

<フローID>.* = <サブハンドラ名>

対象ジョブフローのすべてのジョブを指定のサブハンドラで実行する

4

* = <サブハンドラ名>

対象バッチのすべてのジョブを指定のサブハンドラで実行する

一つの設定ファイルには複数の設定を記載することができます。あるジョブの実行が2つ以上の設定に該当する場合、優先順位が最も小さい行に従います 7 。

対応する振り分け設定ファイルが存在しない場合や、設定ファイル内にマッチする行が存在しない場合、 default という名前のサブハンドラを利用してジョブを実行します。

Attention

現在のAsakusa Frameworkでは、バッチコンパイルのたびにステージIDがランダムに決定されます。ステージIDまで指定して設定を振り分ける場合にはアプリケーションの再デプロイの際に意図した設定が効かなくなる可能性があるため注意が必要です。

Hint

ステージIDについては、 Asakusa DSLユーザーガイド - Batch DSLコンパイラが生成するバッチアプリケーション を参照してください。

5

例えばバッチIDが example.summarizeSales の場合、振り分け設定ファイル名は example.summarizeSales.properties となります。

6

利用可能なフェーズについては YAESSユーザーガイド - Asakusa Frameworkのバッチ構造 を参照してください。なお、 setup と cleanup フェーズは振り分けハンドラ側の設定が優先されます。

7

振り分け設定ファイル内に記載した行の順序は、設定の優先度に影響しません。

設定例

複数の実行環境にジョブフローを振り分ける例

以下はローカル環境上のHadoopの設定と、リモート環境上のHadopの設定を定義し、ジョブフロー単位で使用するHadoopを振り分ける設定例(構成ファイルの一部)です。 2つのHadoopクラスターを処理に応じて使い分ける場合などを想定しています。

ローカル環境上の設定に対するサブハンドラには default を、リモート環境の設定に対するサブハンドラには remote という名前をそれぞれ指定しています。

yaess.properties

# 振り分けハンドラ本体
hadoop = com.asakusafw.yaess.multidispatch.HadoopScriptHandlerDispatcher
hadoop.conf.directory = ${ASAKUSA_HOME}/yaess/conf/multidispatch/

command.* = com.asakusafw.yaess.multidispatch.CommandScriptHandlerDispatcher
command.*.conf.directory = ${ASAKUSA_HOME}/yaess/conf/multidispatch/

# ローカル環境向けサブハンドラ (default)
hadoop.default = com.asakusafw.yaess.basic.BasicHadoopScriptHandler
hadoop.default.resource = hadoop-local
hadoop.default.env.HADOOP_CMD = /usr/bin/hadoop
hadoop.default.env.ASAKUSA_HOME = ${ASAKUSA_HOME}

command.*.default = com.asakusafw.yaess.basic.BasicCommandScriptHandler
command.*.default.resource = asakusa-local
command.*.default.env.ASAKUSA_HOME = ${ASAKUSA_HOME}

# リモート環境向けサブハンドラ (remote)
hadoop.remote = com.asakusafw.yaess.jsch.SshHadoopScriptHandler
hadoop.remote.ssh.user=asakusa
hadoop.remote.ssh.host=example.com
hadoop.remote.ssh.port=22
hadoop.remote.ssh.privateKey=${HOME}/.ssh/id_dsa
hadoop.remote.resource = hadoop-remote
hadoop.remote.env.HADOOP_CMD = /usr/bin/hadoop
hadoop.remote.env.ASAKUSA_HOME = /home/asakusa/asakusafw

command.*.remote = com.asakusafw.yaess.jsch.SshCommandScriptHandler
command.*.remote.ssh.user=asakusa
command.*.remote.ssh.host=example.com
command.*.remote.ssh.port=22
command.*.remote.ssh.privateKey=${HOME}/.ssh/id_dsa
command.*.remote.resource = asakusa-remote
command.*.remote.env.ASAKUSA_HOME = /home/asakusa/asakusafw

そして、 md.batch というバッチに含まれる farexec というジョブフローのみをリモート環境で実行し、それ以外のすべての処理をローカル環境で動作させる場合を考えます。

まず、各 .conf.directory で指定したディレクトリ以下に、バッチ md.batch に対応する振り分け設定ファイルとして md.batch.properties というファイルを作成します。上記の例では、 $ASAKUSA_HOME/yaess/conf/multidispatch/md.batch.properties というパスになります。このファイルを以下のように定義します。

md.batch.properties

# farexec だけ remote で実行
farexec.* = remote

# それ以外は default で実行
* = default

Note

上記のように完全に異なる2つ以上の環境を併用する場合、ジョブフローまたはバッチの単位で振り分けを行うとよいでしょう。フェーズやジョブなどジョブフローより細かい単位で振り分けを行った場合、ジョブフロー実行中の中間結果がジョブ間で共有されないため、通常は正しく動作しません。

なお、複数のクラスターでデフォルトのファイルシステムを共有している場合、上記は問題になりません。

単一の実行環境を異なる設定で利用する例

以下は同一のHadoopを異なる設定で利用する設定例(構成ファイルの一部)です。振り分けの設定をチューニンパラメータとして利用する場合などを想定しています。

デフォルトの設定を利用するサブハンドラには default を、Reduceタスク数を4に設定したサブハンドラには reduce4 を、Reduceタスク数を8に設定したサブハンドラには reduce8 という名前をそれぞれ指定しています。

yaess.properties

# 振り分けハンドラ本体
hadoop = com.asakusafw.yaess.multidispatch.HadoopScriptHandlerDispatcher
hadoop.conf.directory = ${HOME}/.asakusa/multidispatch

# デフォルト設定を利用するサブハンドラ (default)
hadoop.default = com.asakusafw.yaess.basic.BasicHadoopScriptHandler
hadoop.default.resource = hadoop
hadoop.default.env.HADOOP_CMD = /usr/bin/hadoop
hadoop.default.env.ASAKUSA_HOME = ${ASAKUSA_HOME}

# 別の設定を利用するサブハンドラ (reduce4)
hadoop.reduce4 = com.asakusafw.yaess.basic.BasicHadoopScriptHandler
hadoop.reduce4.resource = hadoop
hadoop.reduce4.prop.mapred.reduce.tasks = 4
hadoop.reduce4.env.HADOOP_CMD = /usr/bin/hadoop
hadoop.reduce4.env.ASAKUSA_HOME = ${ASAKUSA_HOME}

# 別の設定を利用するサブハンドラ (reduce8)
hadoop.reduce8 = com.asakusafw.yaess.basic.BasicHadoopScriptHandler
hadoop.reduce8.resource = hadoop
hadoop.reduce8.prop.mapred.reduce.tasks = 8
hadoop.reduce8.env.HADOOP_CMD = /usr/bin/hadoop
hadoop.reduce8.env.ASAKUSA_HOME = ${ASAKUSA_HOME}

そして、 md.batch というバッチに含まれる medium というジョブフローの epilogue フェーズのみで mapred.reduce.tasks = 4 が有効になり、同ジョブフローのそれ以外のフェーズでは mapred.reduce.tasks = 8 が有効になるような例を考えます。

上記の例では、 $HOME/.asakusa/multidispatch/md.batch.properties というファイルを以下のように定義します。

md.batch.properties

medium.epilogue.* = reduce4
medium.* = reduce8

この場合、 medium.epilogue.* = reduce4 の方が medium.* = reduce8 よりも優先されるため、 epilogue フェーズではサブハンドラ reduce4 を利用します。また、 それ以外のフェーズでは reduce8 を利用します。

なお、上記に記載されていないジョブフローでは、デフォルト設定の default を利用します。

YAESS JobQueue

Deprecated

本バージョンでは、 YAESS JobQueueの利用は非推奨となっています。

この文書では、シンプルなHadoopジョブの実行を制御するJobQueue(JobQueueサーバーおよび、それをYAESSと連携して利用するJobQueueクライアントプラグイン asakusa-yaess-jobqueue )の利用方法について解説します。

YAESS がリモートマシン上に配置したJobQueueサーバーを経由してバッチを実行することで、YAESS本体の設定とは独立してリモートマシンのリソースを簡易的に制御することが可能です。また、JobQueueサーバーとJobQueueクライアントプラグインはHTTP経由で非同期的に通信し、ジョブの状況を監視するため、Hadoopのジョブ実行が長時間に渡る場合や、通信路が不安定な場合などに、組み込みで提供されているSSH経由での通信よりも安定した動作が見込めます。

JobQueueの概要

YAESS JobQueueが提供するコンポーネントとその機能について簡単に紹介します。

コンポーネント構成

JobQueueは主に2つのコンポーネントで構成されています。

JobQueueサーバー

Hadoopのジョブを実行するサービスです。 HTTP経由でHadoopジョブ実行リクエストを受け取り、Hadoopコマンドを利用してジョブを起動します。また、ジョブ実行リクエストを内部のキューに一度蓄えて、同時に実行可能なジョブ数を制御できます。

このコンポーネントは、Hadoopサービス群と通信するHadoopクライアントマシン上に配置します。

JobQueueクライアントプラグイン

JobQueueサーバーにHadoopジョブ実行リクエストを送るクライアントで、 YAESSのHadoopジョブハンドラプラグインとして提供されます。 JobQueueサーバーを経由してYAESSからHadoopジョブを実行できます。

このコンポーネントは、YAESSを実行するマシン上にYAESSのプラグインとして配置します。

Hadoopジョブハンドラプラグインは、 YAESSユーザーガイド - Hadoopジョブの実行 で説明しているようなHadoopジョブの実行方法を決定します。構成ファイルの hadoop セクションの hadoop プロパティに使用するHadoopジョブハンドラプラグインを設定します。構成ファイルの設定方法については後述の JobQueueを利用したHadoopジョブの実行 で解説します。

機能概要

JobQueueは以下のような機能を持っています。

同時実行数制御

JobQueueサーバーから同時に実行可能なHadoopジョブの個数を制限できます。

標準出力の保存

JobQueueサーバーからジョブを実行した際の標準出力および標準エラー出力を、ジョブごとに保存できます。

HTTPS通信

HTTPだけでなくHTTPSによる通信も可能です。

ベーシック認証

JobQueueサーバーとの通信時にHTTPのベーシック認証を利用可能です。

ラウンドロビン処理

複数のJobQueueサーバーを登録すると、ラウンドロビン方式でバッチ内のHadoopジョブを振り分けて実行します。一部のサーバーを利用不可能になった場合、そのサーバーをブラックリストに追加して同一バッチ内で利用しないようにします。

JobQueueを利用する際の構成例

以下はJobQueueを利用する際の構成例です。

単一構成

JobQueueサーバーを一台のマシンにインストールする場合、次のような構成をとります。

Hadoopコマンドを利用できるマシン(上図ではHadoopクライアントマシン)でJobQueueサーバーを実行し、そこに対してYAESSからJobQueueクライアントプラグインを利用して通信します。

冗長構成

単一構成 ではJobQueueサーバーが単一障害点になるという問題があるため、JobQueueサーバーを複数用意する冗長構成も検討してください。

冗長構成では単一構成と異なりJobQueueサーバーを複数実行します。上図では2台の異なるマシン上でそれぞれJobQueueサーバーを実行しています。 JobQueueクライアントプラグインに複数のJobQueueサーバーを登録すると、ラウンドロビン方式でそれぞれのJobQueueサーバーに対して交互にジョブ実行のリクエストを発行します。

JobQueueクライアントプラグインが、いずれかのJobQueueサーバーのダウンを検出すると、該当のサーバーをブラックリストに登録し、同一のバッチ内でそのサーバーを利用しないようにします。 JobQueueサーバーがダウンから復旧したら、次回以降のYAESSの実行ではそのサーバーを再度利用するようになります。

JobQueueのデプロイメント構成

JobQueueをデプロイするにあたって、まずはAsakusa Frameworkの全体構成を決定する必要があります。上述の JobQueueを利用する際の構成例 を参考に構成を検討してください。

また、Asakusa Frameworkが提供する外部システム連携の機能に従って、デプロイメント構成を検討します。これについて、詳しくは システム構成の検討 を参考にしてください。このドキュメントの「モジュール」の説明に対応づけると、JobQueueのコンポーネントは以下のモジュールに含まれることになります。

JobQueueサーバー: Hadoopクライアントモジュール

JobQueueクライアントプラグイン: バッチ起動モジュール

以降では運用環境に対して、JobQueueサーバーとJobQueueクライアントプラグインを導入し利用する方法について説明します。

JobQueueサーバーの利用方法

JobQueueサーバーは、Servlet API 3.0に対応したサーブレットコンテナ上のWebアプリケーションとして動作します。ここでは、Apache Tomcat 1 Version 7(以下、Tomcatと表記します)を使ったJobQueueサーバーの利用方法を説明します。

Tomcatの構築手順やSSL、ベーシック認証の設定等は、Tomcatの公式ドキュメント 2 等を参考にしてください。以降、Tomcatをインストールしたディレクトリを、 ${CATALINA_HOME} と表記します。

1

http://tomcat.apache.org

2

http://tomcat.apache.org/tomcat-7.0-doc/index.html

JobQueueサーバー・コンポーネントのインストール

JobQueueサーバーに必要なコンポーネントを以下のページからダウンロードします。

https://github.com/asakusafw/asakusafw-jobqueue-server/wiki/Downloads

ダウンロードが完了したら、以下の例を参考にしてJobQueueサーバーのコンポーネントを $ASAKUSA_HOME にインストールします (標準の ~/Downloads にダウンロードした場合の例です) 。

cd ~/Downloads
cp asakusa-jobqueue-server-*.tar.gz "$ASAKUSA_HOME"
cd "$ASAKUSA_HOME"
tar zxvf asakusa-jobqueue-server-*.tar.gz
find "$ASAKUSA_HOME" -name "*.sh" | xargs chmod u+x

JobQueueサーバーの設定

JobQueueサーバーの動作に必要な設定を行います。 $ASAKUSA_HOME/jobqueue/conf/jobqueue.properties をエディタで開き、修正を行なってください。

JobQueueサーバーの設定

名前

値

core.worker

同時実行可能なジョブのスロット数。YAESSの並列実行の設定やマシンリソースなどに応じて設定を行います。

hadoop.log.dir

Hadoopジョブ実行時のログ出力先。

ここで指定したログディレクトリ配下にJobQueueサーバーがJobQueueクライアントプラグインからジョブ実行リクエストを受け付ける単位で生成される JRID(Job Request ID)の値でディレクトリが作成され、そのディレクトリ配下に stdout と stderr というファイル名で、Hadoopジョブが出力した標準出力、標準エラー出力の内容が出力されます。

JRIDはJobQueueクライアントプラグインやJobQueueサーバーが出力するログに出力されます。問題分析の際にはこれらのログからエラートなったジョブのログを特定することができます。

このディレクトリ配下のディレクトリ/ファイルは自動的には削除されないため、必要に応じてクリーニングを行なってください。

Hadoopジョブの設定

JobQueueサーバーがキックするHadoopジョブに関する環境変数の設定を行います。 $ASAKUSA_HOME/jobqueue-hadoop/conf/env.sh をエディタで開き、修正を行なってください。

Hadoopジョブの設定

名前

値

JQ_HADOOP_PROPERTIES

Hadoopジョブに追加のGenericオプションを指定することができます。

HADOOP_TMP_DIR

ジョブの実行ごとに指定のディレクトリ以下にHadoopのテンポラリ領域を作成します。

省略された場合は、Hadoopのデフォルトのテンポラリ領域を使用し、全てのジョブで共有します。

このディレクトリはHadoopのジョブ実行毎にJRIDを持つサブディレクトリが作成され、このディレクトリ配下にジョブ実行時のワークファイルが作成されます。ジョブ実行時のワークファイルはジョブが正常に終了した場合に自動的に削除しますが、ジョブが異常終了した場合には問題分析のため保持するようになっています。

以下は $ASAKUSA_HOME/jobqueue-hadoop/conf/env.sh の例です。

export JQ_HADOOP_PROPERTIES="-D com.example.property=example"
export HADOOP_TMP_DIR="/tmp/hadoop-${USER}"

Attention

使用するHadoopを明示的に指定する場合、ここで環境変数 HADOOP_CMD や HADOOP_HOME 設定する必要があります。 hadoop コマンドのパスが通っている場合、 hadoop コマンドを経由してHadoopを起動します。

JobQueueサーバーのデプロイ

$ASAKUSA_HOME/webapps/jobqueue.war をTomcatにデプロイしてください。

Tomcatにデプロイするには、 jobqueue.war ファイルを $CATALINA_HOME/webapps にコピーするか、次のようなコンテキスト設定ファイルで jobqueue.war ファイルのパスを指定してください。

例) $CATALINA_HOME/conf/Catalina/localhost/jobqueue.xml (環境変数 $ASAKUSA_HOME が /home/asakusa/asakusa の場合)

<Context docBase="/home/asakusa/asakusa/webapps/jobqueue.war" />

環境変数の設定

Tomcat起動時に、JobQueueサーバーの利用に必要となる環境変数を設定します。

~/.profile をエディタで開き、最下行に以下の定義を追加します。

export JAVA_HOME=/usr/lib/jvm/jdk-6
export ASAKUSA_HOME=$HOME/asakusa
export CATALINA_OPTS='-DapplyEvolutions.default=true'

~/.profile を保存した後、設定した環境変数をターミナル上のシェルに反映させるため、以下のコマンドを実行します。

. ~/.profile

JobQueueサーバーのログ出力

JobQueueサーバーはログ出力にLogback 3 を利用しています。

標準ではコンソールに出力されますが、出力先やログレベルを変更する場合にはLogbackの設定を変更する必要があります。以下はLogbackの設定ファイル例です。

<configuration>

  <conversionRule conversionWord="coloredLevel" converterClass="play.api.Logger$ColoredLevel" />

  <appender name="FILE" class="ch.qos.logback.core.FileAppender">
    <file>/tmp/asakusa/log/jobqueue-server.log</file>
    <append>true</append>
    <encoder>
      <pattern>%d{yyyy/MM/dd HH:mm:ss} %-5level [%thread] %msg%n</pattern>
    </encoder>
  </appender>

  <logger name="play" level="INFO" />
  <logger name="application" level="INFO" />

  <!-- Off these ones as they are annoying, and anyway we manage configuration ourself -->
  <logger name="com.avaje.ebean.config.PropertyMapLoader" level="OFF" />
  <logger name="com.avaje.ebeaninternal.server.core.XmlConfigLoader" level="OFF" />
  <logger name="com.avaje.ebeaninternal.server.lib.BackgroundThread" level="OFF" />

  <root level="INFO">
    <appender-ref ref="FILE" />
  </root>

</configuration>

JobQueueサーバーが設定ファイルを使用するには、上記の CATALINA_OPTS 環境変数に以下のように設定を追加します。

export CATALINA_OPTS='-DapplyEvolutions.default=true -Dlogger.file=/path/to/logger.xml'

3

http://logback.qos.ch/

Tomcatの起動

ドキュメントに従ってTomcatを起動してください。

Attention

Tomcatは各デプロイメントガイドで説明したAsakusa Framework管理用のOSユーザー( ASAKUSA_USER )から実行するように設定してください。

動作確認

デプロイ先のURLのコンテキストルート 4 にアクセスして、次のようなJSONが出力されればJobQueueサーバーが正しく動作しています。

{"application":"asakusa-jobqueue","configurations":{"ASAKUSA_HOME":"/home/asakusa/asakusa","core.worker":4,"hadoop.log.dir":"/tmp/hadoop-asakusa/logs"}}

4

コンテキストパスを jobqueue にした場合、 http://localhost:8080/jobqueue にアクセスしてください。

JobQueueクライアントプラグインの利用方法

JobQueueクライアントプラグインはYAESSのプラグインライブラリとして提供されています。ここではその導入と利用方法について説明します。

プラグインの登録

このプラグインを利用するには、 asakusa-yaess-jobqueue というプラグインライブラリをYAESSに登録します。

JobQueueクライアントプラグインは拡張モジュール ext-yaess-jobqueue-plugin として提供されています。拡張モジュールのデプロイ方法については、 Asakusa Gradle Plugin ユーザーガイド を参照してください。

JobQueueを利用したHadoopジョブの実行

JobQueueを利用してHadoopジョブを実行する場合、構成ファイルの hadoop セクションに以下の内容を設定します。

JobQueueを利用する設定

名前

値

hadoop

com.asakusafw.yaess.jobqueue.QueueHadoopScriptHandler [https://docs.asakusafw.com/0.10.3/release/api/com/asakusafw/yaess/jobqueue/QueueHadoopScriptHandler.html]

hadoop.1.url

JobQueueサーバーのURL

hadoop.1.user

JobQueueサーバーの認証ユーザー名

hadoop.1.password

JobQueueサーバーの認証パスワード

hadoop.timeout

ジョブ登録時のタイムアウト (ミリ秒)

hadoop.pollingInterval

ジョブ状態の問い合わせ間隔 (ミリ秒)

hadoop JobQueueクライアントプラグイン用のHadoopジョブハンドラプラグインクラスを指定します。 YAESS導入時には hadoop には標準的なハンドラクラスが設定されているので、この設定を変更します。

hadoop.1.url には、対象のJobQueueサーバーが動作しているコンテキストパスのルートまでを指定します。現在のところ、プロトコルにはHTTPとHTTPSを利用可能で、URLに認証情報を含めることはできません。

hadoop.1.user と hadoop.1.password はそれぞれ上記URLに対する認証情報です。認証を行わない場合、これらの認証情報は省略可能です。

hadoop.timeout と hadoop.pollingInterval はいずれも省略可能です。それぞれJobQueueサーバーに対する通信のタイムアウトと問い合わせ間隔を指定します。省略した場合、タイムアウトは 10000 、問い合わせ間隔は 1000 をそれぞれ既定値として利用します。

上記のうち、先頭の hadoop を除くすべての項目には ${変数名} という形式で、YAESSを起動した環境の環境変数を含められます。

Attention

JobQueueクライアントプラグイン用のHadoopジョブハンドラプラグインを指定した場合は、 hadoop.env から始まるプロパティを使用した環境変数の引渡しの仕組みは使用出来ません。

このため、デフォルトのYAESSの構成ファイルで設定されている hadoop.env.HADOOP_CMD や hadoop.env.ASAKUSA_HOME を設定している場合は、これらのプロパティを削除してください。

冗長構成用の設定

複数のJobQueueサーバーを利用してラウンドロビン方式でHadoopジョブを実行する場合、 JobQueueを利用したHadoopジョブの実行 に加えて以下の設定を追加します。

ラウンドロビン方式を利用する設定

名前

値

hadoop.<n>.url

JobQueueサーバーのURL

hadoop.<n>.user

JobQueueサーバーの認証ユーザー名

hadoop.<n>.password

JobQueueサーバーの認証パスワード

上記の <n> の部分には 2 以上の整数を指定し、それらに対してURL、ユーザー名、パスワードをそれぞれ指定します。ただし、認証を必要としないJobQueueに対しては、ユーザー名とパスワードを省略可能です。

この <n> の箇所を 2 , 3 , … と次々増やしていくことで、より多くのJobQueueサーバーを登録できます。これらはバッチ実行の際に、ラウンドロビン方式で順番に利用され、サーバーが動作していない際にはブラックリストに入れられます。

Attention

サーバーが動作していない場合にはラウンドロビンから外されますが、ジョブの実行中にサーバーがダウンした場合にはその場でジョブの実行が失敗します。

設定例

ジョブ実行クラスターの振り分けと組み合わせて利用する例

以下は ジョブ実行クラスターの振り分け とJobQueueを組み合わせて利用する設定例(構成ファイルの一部)です。ローカル環境上の設定に対するサブハンドラには default を、JobQueueを経由するサブハンドラには jobqueue という名前をそれぞれ指定しています。 Jobqueueサーバーは2台の冗長構成をもち、それぞれBASIC認証を使用します。

# 振り分けハンドラ本体
hadoop = com.asakusafw.yaess.multidispatch.HadoopScriptHandlerDispatcher
hadoop.conf.directory = ${HOME}/.asakusa/multidispatch

# デフォルト設定を利用するサブハンドラ (default)
hadoop.default = com.asakusafw.yaess.basic.BasicHadoopScriptHandler
hadoop.default.resource = hadoop-default
hadoop.default.env.HADOOP_CMD = /usr/bin/hadoop
hadoop.default.env.ASAKUSA_HOME = ${ASAKUSA_HOME}

#JobQueueを利用するサブハンドラ (jobqueue)
hadoop.jobqueue = com.asakusafw.yaess.jobqueue.QueueHadoopScriptHandler
hadoop.jobqueue.resource = hadoop-jobqueue
hadoop.jobqueue.timeout = 30000
hadoop.jobqueue.pollingInterval = 500

#JobQueueサーバーは2台の冗長構成
hadoop.jobqueue.1.url = http://jobqueue-server1:8080/jobqueue
hadoop.jobqueue.1.user = asakusa1
hadoop.jobqueue.1.password = asakusa1
hadoop.jobqueue.2.url = http://jobqueue-server2:8080/jobqueue
hadoop.jobqueue.2.user = asakusa2
hadoop.jobqueue.2.password = asakusa2

YAESSに関するログ一覧

この文書では、YAESSが利用するログの一覧を紹介します。

YAESS本体のログ

YAESSのプラグイン部分を除く本体が出力するログは以下の通りです。

YAESS本体のログ

ログコード

レベル

概要

YS-BOOTSTRAP-I00000

情報

YAESS全体を開始

YS-BOOTSTRAP-I00999

情報

YAESS全体を終了

YS-BOOTSTRAP-I00001

情報

ジョブネットを起動

YS-BOOTSTRAP-E00001

エラー

YAESSの起動引数が不正

YS-BOOTSTRAP-E00002

エラー

YAESSのプラグイン初期化に失敗した

YS-BOOTSTRAP-E00003

エラー

ジョブネットの実行に失敗した

YS-BOOTSTRAP-E01001

エラー

YAESSのプロファイル設定を読み出せない

YS-BOOTSTRAP-E01002

エラー

YAESSのジョブネットスクリプトファイルを読み出せない

YS-BOOTSTRAP-W99001

警告

プラグインライブラリの読み出しに失敗

YS-CORE-I01000

情報

バッチの実行を開始

YS-CORE-I01999

情報

バッチの実行を終了

YS-CORE-I01001

情報

バッチの実行が正常終了した

YS-CORE-I01003

情報

ジョブフローの実行をスケジュールした

YS-CORE-I01004

情報

実行中またはスケジュールされたジョブフローの実行をキャンセル

YS-CORE-I01005

情報

ジョブフローの実行がキャンセルされた

YS-CORE-W01001

警告

バッチの実行中に割り込みが要求された

YS-CORE-W01002

警告

スケジュールされたジョブフローのシャットダウンに失敗した

YS-CORE-E01001

エラー

バッチの実行が異常終了した

YS-CORE-I02000

情報

ジョブフローの実行を開始

YS-CORE-I02999

情報

ジョブフローの実行を終了

YS-CORE-I02001

情報

ジョブフローの実行が正常終了した

YS-CORE-I02002

情報

ジョブフローの実行をスキップした

YS-CORE-I02003

情報

ジョブフローの実行が中断されたため、finalizeフェーズを実行開始

YS-CORE-W02001

警告

ジョブフローの実行中に割り込みが要求された

YS-CORE-W02002

警告

ジョブフローの実行が中断されたため、finalizeフェーズを実行したが失敗した

YS-CORE-W02003

警告

cleanupフェーズの実行に失敗 (ジョブフロー全体としては成功)

YS-CORE-E02001

エラー

ジョブフローの実行が異常終了した

YS-CORE-I03000

情報

フェーズの実行を開始

YS-CORE-I03999

情報

フェーズの実行を終了

YS-CORE-I03001

情報

フェーズの実行が正常終了した

YS-CORE-I03002

情報

フェーズの実行をスキップした

YS-CORE-W03001

警告

フェーズの実行中に割り込みが要求された

YS-CORE-E03001

エラー

フェーズの実行が異常終了した

YS-CORE-I04000

情報

ジョブの実行を開始

YS-CORE-I04999

情報

ジョブの実行を終了

YS-CORE-I04001

情報

ジョブフローの実行が正常終了した

YS-CORE-W04001

警告

ジョブの実行中に割り込みが要求された

YS-CORE-E04001

エラー

ジョブの実行が異常終了した

YS-CORE-E10001

エラー

プロファイルに指定された環境変数の展開に失敗した

YS-CORE-I51001

情報

setupジョブで行うべきことがなにもなかった

YS-CORE-I51002

情報

cleanupジョブで行うべきことがなにもなかった

YS-CORE-W99001

警告

出力のリダイレクト中に出力先にデータを書き出せなかった

YS-CORE-W99002

警告

出力のリダイレクト中に入力元からデータを読み出せなかった

YS-CORE-W99003

警告

出力のリダイレクト後に出力先を正常に閉じられなかった

YS-CORE-W99004

警告

出力のリダイレクト後に入力元を正常に閉じられなかった

YAESS組み込みプラグインに関するログ

クラス名が com.asakusafw.yaess.basic.Basic から始まる組み込みのプラグインを利用する部分のログは以下の通りです。

YAESS本体のログ

ログコード

レベル

概要

YS-BASIC-W10001

警告

廃止されたプロパティを利用している

YS-BASIC-E21001

エラー

(廃止) ジョブスケジューラがジョブの実行中にエラーが発生した

YS-BASIC-W41001

警告

実行ロックの開放に失敗した

YS-BASIC-W41002

警告

実行ロック完了後にファイルを正常に閉じられなかった

YS-BASIC-W41003

警告

実行ロック完了後にファイルを削除できなかった

YS-BASIC-E41001

エラー

バッチ実行時に実行ロックを取得できなかった

YS-BASIC-E41002

エラー

ジョブフロー実行時にロックを取得できなかった

YS-BASIC-I51001

情報

Hadoopのクリーンアップ処理を開始しようとしている

YS-BASIC-I51002

情報

Hadoopのクリーンアップ処理を設定によりスキップした

ジョブの並列実行プラグインに関するログ

ジョブの並列実行 ( asakusa-yaess-paralleljob ) を利用する部分のログは以下の通りです。

YAESS本体のログ

ログコード

レベル

概要

YS-PARALLELJOB-I01001

情報

指定のリソースプールを利用してジョブを実行する

YS-PARALLELJOB-W01001

警告

指定されたリソースに対するリソースプールが定義されていない (defaultを利用して実行する)

SSH接続プラグインに関するログ

SSHによるジョブの実行 ( asakusa-yaess-jsch ) を利用する部分のログは以下の通りです。

YAESS本体のログ

ログコード

レベル

概要

YS-JSCH-I00001

情報

SSHのセッションを開始しようといている

YS-JSCH-I00002

情報

SSHのセッションを開始した

YS-JSCH-I00003

情報

SSHを利用してコマンドの実行を開始しようとしている

YS-JSCH-I00004

情報

SSHを利用してコマンドの実行を開始した

YS-JSCH-I00005

情報

SSHのセッションを終了した

YS-JSCH-W00001

警告

SSHを利用したコマンドの実行時に、正しくない形式の環境変数の転送を省略した

YS-JSCH-E00001

エラー

SSHのセッション内で処理が失敗した

ジョブフローごとの進捗状況出力プラグインに関するログ

ジョブフローごとの進捗状況出力 ( asakusa-yaess-flowlog ) を利用する部分のログは以下の通りです。

YAESS本体のログ

ログコード

レベル

概要

YS-FLOWLOG-I01001

情報

前回退避したジョブフローの進捗状況ファイルを削除開始

YS-FLOWLOG-I01002

情報

成功したジョブフローの進捗状況ファイルを削除開始

YS-FLOWLOG-I01003

情報

成功したジョブフローの進捗状況ファイルを退避開始

YS-FLOWLOG-W01001

警告

進捗状況ファイルの出力先ディレクトリの作成に失敗した

YS-FLOWLOG-W01002

警告

前回退避したジョブフローの進捗状況ファイルの削除に失敗した

YS-FLOWLOG-W01003

警告

成功したジョブフローの進捗状況ファイルの削除に失敗した

YS-FLOWLOG-W01004

警告

成功したジョブフローの進捗状況ファイルの退避に失敗した

実行クラスター振り分けプラグインに関するログ

実行クラスター振り分け ( asakusa-yaess-multidispatch ) を利用する部分のログは以下の通りです。

YAESS本体のログ

ログコード

レベル

概要

YS-MULTIDISPATCH-I00001

情報

プロファイルに指定された振り分け設定ディレクトリが存在しない

YS-MULTIDISPATCH-I01001

情報

setupフェーズのジョブを指定のサブハンドラで実行開始

YS-MULTIDISPATCH-I01002

情報

ジョブを指定のサブハンドラで実行開始

YS-MULTIDISPATCH-I01003

情報

cleanupフェーズのジョブを指定のサブハンドラで実行開始

YS-MULTIDISPATCH-E01001

エラー

振り分け設定ファイルの読み込みに失敗した

ジョブキュープラグインに関するログ

ジョブキュー ( asakusa-yaess-jobqueue ) を利用する部分のログは以下の通りです。

YAESS本体のログ

ログコード

レベル

概要

YS-JOBQUEUE-I01001

情報

ジョブキューサーバーへのジョブ登録処理を開始

YS-JOBQUEUE-I01002

情報

ジョブキューサーバーへのジョブ登録処理を終了

YS-JOBQUEUE-I01003

情報

登録されたジョブの実行予約処理を開始

YS-JOBQUEUE-I01004

情報

登録されたジョブの実行予約処理を終了

YS-JOBQUEUE-I01005

情報

実行予約したジョブの監視を開始

YS-JOBQUEUE-I01006

情報

実行予約したジョブの監視を終了

YS-JOBQUEUE-W01001

警告

一つのクライアントでジョブキューサーバーへのジョブ登録に失敗した

YS-JOBQUEUE-E01001

エラー

すべてのクライアントでジョブキューサーバーへのジョブ登録に失敗した

YS-JOBQUEUE-E01002

エラー

登録されたジョブの実行予約に失敗した

YS-JOBQUEUE-E01003

エラー

実行予約したジョブの監視に失敗した

コマンドラインインターフェース - Asakusa CLI

Asakusa CLI

Asakusa CLI ( asakusa コマンド ) はバッチアプリケーションの開発支援ツール、および運用ツールを提供するコマンドラインインターフェースです。 Asakusa CLIは主に以下のような機能を提供します。

asakusa run - 簡易的なバッチアプリケーション実行ツール

asakusa list - DSL情報を様々な観点や粒度でリスト化して表示

asakusa generate - DSL情報からデータフロー構造やコンパイル後の実行計画などのグラフ情報を生成

関連するドキュメント

Asakusa CLI ユーザーガイド

Asakusa CLI ユーザーガイド

この文書では、Asakusa CLI ( asakusa コマンド ) の利用方法について説明します。

Attention

Asakusa CLI は Asakusa on MapReduce で生成したバッチアプリケーションには対応していません。

セットアップ

Asakusa CLIは開発環境と運用環境の両方で利用することができます。

開発環境のセットアップ

開発環境では、開発環境用のAsakusa Frameworkがインストールされた状態であればAsakusa CLIを利用することができます。開発環境上でAsakusa Frameworkをインストールする手順については、 Asakusa Framework スタートガイド や Asakusa Gradle Plugin ユーザーガイド などを参照してください。

運用環境のセットアップ

運用環境では、Asakusa Frameworkのデプロイメントアーカイブを配備した状態であればAsakusa CLIを利用することができます。運用環境上でデプロイメントアーカイブを配置する手順については、 Asakusa Framework デプロイメントガイド などを参照してください。

asakusa コマンド

Asakusa CLIの各機能は asakusa コマンドを通して利用します。セットアップが完了した環境であれば、 asakusa コマンドは $ASAKUSA_HOME/bin 配下に配置されています。コマンドラインから asakusa コマンドを利用する場合、 $ASAKUSA_HOME/bin 配下に環境変数 PATH を通しておくと便利です。

以降本書で asakusa コマンドを実行する例を示す際には、上記の PATH 環境変数が設定済であるものとします。

正しくセットアップが行われている環境でコマンドラインから asakusa コマンドを実行すると、以下のように表示されます。

$ asakusa
使用方法: asakusa <command> <command options>

利用可能なコマンドの一覧:
    generate - DSLの情報からリソースを生成する。
    list - DSLの情報をリスト形式で表示する。
    run - バッチアプリケーションを実行する。
    version - Asakusa Frameworkのバージョン情報を表示する。

各コマンドの詳しい情報は 'asakusa <command> --help' を参照してください。

上記が表示されず、エラーメッセージが表示されてしまう場合には、セットアップ環境を確認してください。

コマンド体系

サブコマンド

asakusa コマンドはサブコマンドを指定することで様々な機能を呼び出します。サブコマンドには list や run 、 generate といったものがあります。サブコマンドの中には、さらにサブコマンドを要求するものもあります。

コマンドラインから実行する際には、サブコマンド間をスペースで区切って指定します。

例えば、asakusa list batch のように実行すると、環境上に配置されたバッチアプリケーション一覧をリストとして表示します。

$ asakusa list batch
m3bp.example.summarizeSales
spark.example.summarizeSales

パラメータ

多くのサブコマンドでは、サブコマンドに続けてバッチIDなどの処理の対象を指定するパラメータを指定します。

コマンドラインから実行する際には、サブコマンドの後にパラメータをスペースで区切って指定します。

例えば、asakusa list operator は指定したバッチIDに対応するアプリケーションに含まれる演算子の一覧をリストとして表示します。

$ asakusa list operator m3bp.example.summarizeSales
CategorySummaryOperator#checkStore(@MasterCheck)
CategorySummaryOperator#joinItemInfo(@MasterJoin)
CategorySummaryOperator#setErrorMessage(@Update)
CategorySummaryOperator#setErrorMessage(@Update)
CategorySummaryOperator#summarizeByCategory(@Summarize)

オプション

各サブコマンドにはサブコマンド共通、または固有のオプションが存在します。

コマンドラインから実行する際には、サブコマンドの後、またはパラメータ後にスペースで区切って指定します。多くのLinuxコマンドと同様に、いくつかのオプションでは -- から始まる記法の他、 - から始まる短縮記法を利用できます。

オプションによっては、オプション固有のパラメータを指定するものもあります。通常、オプションとそのパラメータはスペースで区切って指定しますが、一部のオプションでは -Akey=value のようにスペースで区切らずに指定することも可能です。

以下はサブコマンド共通の主なオプションです。

-v, --verbose

コマンド実行結果の出力に詳細な情報を含める。

-h, --help

ヘルプメッセージを表示する。サブコマンドが要求するオプションや追加のサブコマンドを確認する。

$ asakusa run --help
Usage: asakusa run [options] batch-ID
  Options:
    -A, --batch-argument
      バッチ引数を指定する。
      Syntax: -Akey=value
      Default: {}
    -B, --batchapps
      バッチアプリケーションのベースディレクトリー (ASAKUSA_BATCHAPPS_HOME)。
    ...

コマンドリファレンス

asakusa コマンドのサブコマンド一覧を以下に示します。

asakusa サブコマンド

サブコマンド

説明

asakusa run

バッチアプリケーションを実行する

asakusa list

バッチアプリケーションのDSL情報をリスト形式で表示する

asakusa generate

バッチアプリケーションのDSL情報から様々なリソースを生成する

asakusa version

Asakusa Frameworkのバージョン情報を表示する。

asakusa run

run は、環境にデプロイされているバッチアプリケーションを実行します。

書式

asakusa run [options] batch-ID

説明

指定したバッチIDに対応するバッチアプリケーションを実行します。バッチ引数を指定する場合はコマンドラインの末尾にオプション -A <変数名>=<値> のように記述します。

$ asakusa run m3bp.example.summarizeSales -A date=2011-04-01

アプリケーションが正常終了した場合は 0 , それ以外の場合は 0 でない終了コードを返します。

オプション

run サブコマンドで使用できる主なオプションを以下に示します。利用可能なすべてのオプションは、コマンドのヘルプを参照してください。

-A, --batch-argument key=value...

実行するバッチアプリケーションのバッチ引数を指定する。

オプションのパラメータは key=value 形式で指定する。また、以下のように複数のバッチ引数を指定可能。

$ asakusa run m3bp.example.app -A key1=value1 -A key2=value2

-O, --output-style

run コマンド内で実行する外部コマンドの出力形式を以下のパラメータで指定します。

STANDARD : 標準出力および標準エラー出力に対して出力する（デフォルト）

LOGGING : run コマンドのロガー 1 に対して出力する

NOTHING : 出力を行わない

1

このログは com.asakusafw.cli.workflow.executor というログ名に対して出力します。また標準の設定ではこのログ名に対してログレベル info が設定されています。ログの設定方法については後述の ログの設定 を参照してください。

Java VMの設定

run でバッチアプリケーションを実行する際には、Java VMをひとつ起動してそのプロセス内で各実行エンジンや外部連携モジュールの起動コマンドを実行します。

このとき、 run を実行するJava VMのオプション引数を、環境変数 ASAKUSA_CLIENT_OPTS で指定できます。

以下は環境変数の設定例です。

export ASAKUSA_CLIENT_OPTS='-Xmx128m'

上記のように書いた場合、Javaのヒープ領域の最大値を 128MB に設定できます。

Attention

ASAKUSA_CLIENT_OPTS が設定の対象とするのは run コマンド用のJava VMの設定で、実行エンジンが使用するJava VMの設定とは異なります。例えば Asakusa on M3BP の実行エンジンが使用するJava VMの設定は ASAKUSA_M3BP_OPTS で指定します。

ログの設定

run コマンドの標準の設定では、標準のログレベルは warn 以上のログを出力するよう設定されています。このため、警告なしにバッチアプリケーションが正常終了する場合、 run コマンドのログは出力されません。

ログレベルを変更するなど、 run コマンドのログ設定を変更するには、 SLF4JのSimpleLogger 2 のシステムプロパティを環境変数 ASAKUSA_CLIENT_OPTS に設定します。

以下は、 info 以上のログを出力するようログレベルを設定してバッチアプリケーションを実行する例です。

export ASAKUSA_CLIENT_OPTS=-Dorg.slf4j.simpleLogger.defaultLogLevel=info
asakusa run m3bp.example.app ...

Attention

ここでの説明で対象とするのは run コマンド用のログの設定で、実行エンジンが使用するログの設定とは異なります。例えば Asakusa on M3BP の実行エンジンが使用するログの設定は $ASAKUSA_HOME/m3bp/conf/logback.xml で指定します。

また、標準の設定では run コマンドで実行する外部コマンドの出力は、標準出力および標準エラー出力に対して出力するようになっています。この出力を run コマンドのロガー経由で出力させるようにするには -O LOGGING オプションを指定します。

asakusa run -O LOGGING m3bp.example.app ...

2

https://www.slf4j.org/api/org/slf4j/impl/SimpleLogger.html

asakusa list

list は、バッチアプリケーションのDSL情報から様々な観点のリストを表示します。 list のサブコマンド一覧を以下に示します。

list サブコマンド

サブコマンド

説明

asakusa list batch

バッチアプリケーションの一覧を表示する

asakusa list parameter

バッチ引数の一覧を表示する

asakusa list jobflow

ジョブフローの一覧を表示する

asakusa list operator

演算子の一覧を表示する

asakusa list directio

Direct I/O の入出力情報の一覧を表示する

asakusa list hive

Direct I/O Hive の入出力情報の一覧を表示する

asakusa list windgate

WindGate の入出力情報の一覧を表示する

asakusa list plan

実行計画の情報を表示する

オプション

list のサブコマンド共通で使用できる主なオプションを以下に示します。

-e, --encoding encoding

出力結果の文字セットエンコーディングを指定する。

デフォルトでは環境の標準エンコーディングを使用する。

-o, --output file

表示結果を指定したファイルパスに保存する。デフォルトでは標準出力に表示結果を出力する。

-v, --verbose

コマンド実行結果の出力に詳細な情報を含める。

Hint

list のサブコマンドはこのオプションの有無で出力形式が大きく異なり、サブコマンドに対応した様々な詳細情報を表示することができます。

--flow, --jobflow flow-id

指定したフローIDに対応するジョブフローに含まれる情報のみを出力する( batch , parameter サブコマンドは指定不可)。

asakusa list batch

batch は環境にデプロイされているバッチアプリケーションの一覧を表示します。

書式

asakusa list batch [options]

使用例

batch を標準のオプションで実行すると、環境にデプロイされているバッチアプリケーションのバッチID一覧を表示します。

$ asakusa list batch
m3bp.example.summarizeSales
spark.example.summarizeSales

batch を詳細オプション付きで実行すると、バッチクラスや @Batch 注釈に定義したコメントも表示します。

$ asakusa list batch -v
m3bp.example.summarizeSales:
      class: com.example.batch.SummarizeBatch
    comment: Asakusa Framework example batch application
spark.example.summarizeSales:
      class: com.example.batch.SummarizeBatch
    comment: Asakusa Framework example batch application

asakusa list parameter

parameter は指定されたバッチIDに対応する、バッチアプリケーションのバッチ引数一覧を表示します。

書式

asakusa list parameter [options] batch-id

使用例

parameter を標準のオプションで実行すると、バッチ引数名 ( key )の一覧を表示します。

$ asakusa list parameter m3bp.example.summarizeSales
date

parameter を詳細オプション付きで実行すると、@Parameter 注釈に定義した属性情報も表示します。

$ asakusa list parameter -v m3bp.example.summarizeSales
date:
      comment: The target date
      pattern: \d{4}-\d{2}-\d{2}
    mandatory: true

asakusa list jobflow

jobflow は指定されたバッチIDに対応する、バッチアプリケーションに含まれるジョブフローの一覧を表示します。

書式

asakusa list jobflow [options] batch-id

使用例

jobflow を標準のオプションで実行すると、バッチアプリケーションに含まれるジョブフローのフローID一覧を表示します。

$ asakusa list jobflow spark.PosDataSummarizationBatch
CleaningJobFlow
SummarizeJobFlow

jobflow を詳細オプション付きで実行すると、ジョブフロー間の依存関係やジョブフローの各フェーズ情報も表示します。

$ asakusa list jobflow -v spark.PosDataSummarizationBatch
CleaningJobFlow (com.asakusafw.tutorial.posdata_summarization.jobflow.CleaningJobFlow):
    blockers: -
    import:
        windgate (@posdata-summarization)
    main:
        spark (@spark)
    export:
        windgate (@posdata-summarization)
    finalize:
        windgate (@posdata-summarization)
SummarizeJobFlow (com.asakusafw.tutorial.posdata_summarization.jobflow.SummarizeJobFlow):
    blockers:
        CleaningJobFlow
    import:
        windgate (@posdata-summarization)
    main:
        spark (@spark)
    export:
        windgate (@posdata-summarization)
    finalize:
        windgate (@posdata-summarization)

asakusa list operator

operator は指定したバッチIDに対応する、バッチアプリケーションに含まれる演算子の一覧を表示します。

書式

asakusa list operator [options] batch-id

使用例

operator を標準のオプションで実行すると、バッチアプリケーションに含まれる演算子の一覧を表示します。フロー部品を使用している場合、フロー部品に含まれる演算子が表示されます。

$ asakusa list operator m3bp.example.summarizeSales
CategorySummaryOperator#checkStore(@MasterCheck)
CategorySummaryOperator#joinItemInfo(@MasterJoin)
CategorySummaryOperator#setErrorMessage(@Update)
CategorySummaryOperator#summarizeByCategory(@Summarize)

operator を詳細オプション付きで実行すると、演算子クラスの完全修飾名や演算子に指定した値引数の情報も表示します。

$ asakusa list operator -v m3bp.example.summarizeSales
com.example.operator.CategorySummaryOperator#checkStore(@MasterCheck){}
com.example.operator.CategorySummaryOperator#joinItemInfo(@MasterJoin){}
com.example.operator.CategorySummaryOperator#setErrorMessage(@Update){message:String=商品不明}
com.example.operator.CategorySummaryOperator#setErrorMessage(@Update){message:String=店舗不明}
com.example.operator.CategorySummaryOperator#summarizeByCategory(@Summarize){}

asakusa list directio

directio は指定したバッチIDに対応する、バッチアプリケーションに含まれるDirect I/Oの入出力一覧を表示します。 directio のサブコマンド一覧を以下に示します。

directio サブコマンド

サブコマンド

説明

input

ファイル入力の定義情報を表示する。

output

ファイル出力の定義情報を表示する。

書式

asakusa list directio {input|output} [options] batch-id

使用例

directio を標準のオプションで実行すると、バッチアプリケーションに含まれるDirect I/Oのベースパスと入出力パターンをそれぞれ表示します。

$ asakusa list directio input m3bp.example.summarizeSales
master::item_info.csv
master::store_info.csv
sales::**/${date}.csv

$ asakusa list directio output m3bp.example.summarizeSales
result/category::result.csv
result/error::${date}.csv

directio を詳細オプション付きで実行すると、Direct I/Oの入出力定義で記述した情報を詳細に表示します。

$ asakusa list directio input -v m3bp.example.summarizeSales
com.example.jobflow.ItemInfoFromCsv:
           base-path: master
    resource-pattern: item_info.csv
           data-type: com.example.modelgen.dmdl.model.ItemInfo
        filter-class: N/A
        format-class: com.example.modelgen.dmdl.csv.ItemInfoCsvFormat
            optional: false
com.example.jobflow.StoreInfoFromCsv:
           base-path: master
    resource-pattern: store_info.csv
           data-type: com.example.modelgen.dmdl.model.StoreInfo
        filter-class: N/A
        format-class: com.example.modelgen.dmdl.csv.StoreInfoCsvFormat
            optional: false
com.example.jobflow.SalesDetailFromCsv:
           base-path: sales
    resource-pattern: **/${date}.csv
           data-type: com.example.modelgen.dmdl.model.SalesDetail
        filter-class: N/A
        format-class: com.example.modelgen.dmdl.csv.SalesDetailCsvFormat
            optional: false

$ asakusa list directio output -v m3bp.example.summarizeSales
com.example.jobflow.CategorySummaryToCsv:
           base-path: result/category
    resource-pattern: result.csv
               order: [-selling_price_total]
     delete-patterns: [*]
           data-type: com.example.modelgen.dmdl.model.CategorySummary
        format-class: com.example.modelgen.dmdl.csv.CategorySummaryCsvFormat
com.example.jobflow.ErrorRecordToCsv:
           base-path: result/error
    resource-pattern: ${date}.csv
               order: [+file_name]
     delete-patterns: [*]
           data-type: com.example.modelgen.dmdl.model.ErrorRecord
        format-class: com.example.modelgen.dmdl.csv.ErrorRecordCsvFormat

asakusa list hive

hive は指定したバッチIDに対応する、バッチアプリケーションに含まれるDirect I/O Hiveの入出力一覧を表示します。 hive のサブコマンド一覧を以下に示します。

hive サブコマンド

サブコマンド

説明

input

Hiveテーブル入力の定義情報を表示する。

output

Hiveテーブル出力の定義情報を表示する。

書式

asakusa list hive {input|output} [options] batch-id

使用例

hive を標準のオプションで実行すると、バッチアプリケーションに含まれるDirect I/O Hiveの入出力テーブル名をそれぞれ表示します。

$ asakusa list hive input m3bp.example.summarizeSales
item_info
sales_detail
store_info

$ asakusa list hive output m3bp.example.summarizeSales
category_summary
error_record

hive を詳細オプション付きで実行すると、Direct I/O Hiveの入出力定義で記述した情報を詳細に表示します。

$ asakusa list hive input m3bp.example.summarizeSales -v
item_info:
           port-name: itemInfo
         description: com.example.jobflow.ItemInfoFromParquet
           base-path: tables/item_info
    resource-pattern: **/*
             columns: [item_code:STRING, item_name:STRING, department_code:STRING, department_name:STRING, category_code:STRING, category_name:STRING, unit_selling_price:INT, registered_date:STRING, begin_date:STRING, end_date:STRING]
          row-format: N/A
      storage-format: PARQUET
          properties: {}
             comment: 商品マスタ
sales_detail:
           port-name: salesDetail
         description: com.example.jobflow.SalesDetailFromOrc
           base-path: tables/sales_detail
    resource-pattern: **/*
             columns: [sales_date_time:TIMESTAMP, store_code:STRING, item_code:STRING, amount:INT, unit_selling_price:INT, selling_price:INT]
          row-format: N/A
      storage-format: ORC
          properties: {orc.stripe.size=67108864, orc.compress=SNAPPY}
             comment: 売上明細
store_info:
           port-name: storeInfo
         description: com.example.jobflow.StoreInfoFromParquet
           base-path: tables/store_info
    resource-pattern: **/*
             columns: [store_code:STRING, store_name:STRING]
          row-format: N/A
      storage-format: PARQUET
          properties: {}
             comment: 店舗マスタ

$ asakusa list hive output m3bp.example.summarizeSales -v
category_summary:
           port-name: categorySummary
         description: com.example.jobflow.CategorySummaryToOrc
           base-path: tables/category_summary
    resource-pattern: *
             columns: [category_code:STRING, amount_total:BIGINT, selling_price_total:BIGINT]
          row-format: N/A
      storage-format: ORC
          properties: {orc.stripe.size=67108864, orc.compress=SNAPPY}
             comment: カテゴリ別売上集計
error_record:
           port-name: errorRecord
         description: com.example.jobflow.ErrorRecordToParquet
           base-path: tables/error_record
    resource-pattern: *
             columns: [sales_date_time:TIMESTAMP, store_code:STRING, item_code:STRING, message:STRING]
          row-format: N/A
      storage-format: PARQUET
          properties: {}
             comment: エラー情報

asakusa list windgate

windgate は指定したバッチIDに対応する、バッチアプリケーションに含まれるWindGateの入出力一覧を表示します。 windgate のサブコマンド一覧を以下に示します。

windgate サブコマンド

サブコマンド

説明

input

WindGate入力の定義情報を表示する。

output

WindGate出力の定義情報を表示する。

書式

asakusa list windgate {input|output} [options] batch-id

使用例

windgate を標準のオプションで実行すると、バッチアプリケーションに含まれるWindGateの入出力情報の定義（プロファイル名、リソース名、テーブル名またはファイル名）をそれぞれ表示します。

$ asakusa list windgate input m3bp.example.summarizeSales
asakusa::jdbc::ITEM_INFO
asakusa::jdbc::SALES_DETAIL
asakusa::jdbc::STORE_INFO

$ asakusa list windgate output m3bp.example.summarizeSales
asakusa::jdbc::CATEGORY_SUMMARY
asakusa::jdbc::ERROR_RECORD

windgate を詳細オプション付きで実行すると、WindGateの入出力定義で記述した情報を詳細に表示します。

$ asakusa list windgate input -v m3bp.example.summarizeSales
com.asakusafw.example.jdbc.jobflow.ItemInfoFromJdbc:
     profile-name: asakusa
    resource-name: jdbc
          columns: ITEM_CODE, ITEM_NAME, DEPARTMENT_CODE, DEPARTMENT_NAME, CATEGORY_CODE, CATEGORY_NAME, UNIT_SELLING_PRICE, REGISTERED_DATE, BEGIN_DATE, END_DATE
      jdbcSupport: com.asakusafw.example.jdbc.modelgen.dmdl.jdbc.ItemInfoJdbcSupport
            table: ITEM_INFO
com.asakusafw.example.jdbc.jobflow.SalesDetailFromJdbc:
     profile-name: asakusa
    resource-name: jdbc
          columns: SALES_DATE_TIME, STORE_CODE, ITEM_CODE, AMOUNT, UNIT_SELLING_PRICE, SELLING_PRICE
      jdbcSupport: com.asakusafw.example.jdbc.modelgen.dmdl.jdbc.SalesDetailJdbcSupport
            table: SALES_DETAIL
com.asakusafw.example.jdbc.jobflow.StoreInfoFromJdbc:
     profile-name: asakusa
    resource-name: jdbc
          columns: STORE_CODE, STORE_NAME
      jdbcSupport: com.asakusafw.example.jdbc.modelgen.dmdl.jdbc.StoreInfoJdbcSupport
            table: STORE_INFO

$ asakusa list windgate output -v m3bp.example.summarizeSales
com.asakusafw.example.jdbc.jobflow.CategorySummaryToJdbc:
     profile-name: asakusa
    resource-name: jdbc
          columns: CATEGORY_CODE, AMOUNT, SELLING_PRICE
      jdbcSupport: com.asakusafw.example.jdbc.modelgen.dmdl.jdbc.CategorySummaryJdbcSupport
        operation: insert_after_truncate
            table: CATEGORY_SUMMARY
com.asakusafw.example.jdbc.jobflow.ErrorRecordToJdbc:
     profile-name: asakusa
    resource-name: jdbc
          columns: SALES_DATE_TIME, STORE_CODE, ITEM_CODE, MESSAGE
      jdbcSupport: com.asakusafw.example.jdbc.modelgen.dmdl.jdbc.ErrorRecordJdbcSupport
        operation: insert_after_truncate
            table: ERROR_RECORD

asakusa list plan

plan は指定したバッチIDに対応する、バッチアプリケーションの実行計画に含まれるvertexの一覧を表示します。

書式

asakusa list plan [options] batch-id

使用例

plan を標準のオプションで実行すると、バッチアプリケーションに含まれるvertex IDの一覧を表示します。

$ asakusa list plan m3bp.example.summarizeSales
_directio-commit
_directio-setup
v0
v1
v2
v3
v4
v5
v6

plan を詳細オプション付きで実行すると、vertex間の依存関係やvertexに含まれる演算子の情報も表示します。

$ asakusa list plan -v m3bp.example.summarizeSales
_directio-commit:
    label: N/A
    blockers: {v4, v6}
    operators: -
_directio-setup:
    label: N/A
    blockers: {}
    operators: -
v0:
    label: ExternalInput(storeInfo)
    blockers: {}
    operators: -
v1:
    label: ExternalInput(itemInfo)
    blockers: {}
    operators: -
v2:
    label: ExternalInput(salesDetail)
    blockers: {v0}
    operators:
        com.example.operator.CategorySummaryOperator#checkStore(@MasterCheck)
        com.example.operator.CategorySummaryOperator#setErrorMessage(@Update)
v3:
    label: @MasterJoin:CategorySummaryOperator.joinItemInfo
    blockers: {v1, v2}
    operators:
        com.example.operator.CategorySummaryOperator#setErrorMessage(@Update)
        com.example.operator.CategorySummaryOperator#joinItemInfo(@MasterJoin)
v4:
    label: ExternalOutput(errorRecord)
    blockers: {_directio-setup, v2, v3}
    operators: -
v5:
    label: @Summarize:CategorySummaryOperator.summarizeByCategory
    blockers: {v3}
    operators:
        com.example.operator.CategorySummaryOperator#summarizeByCategory(@Summarize)
v6:
    label: ExternalOutput(categorySummary)
    blockers: {_directio-setup, v5}
    operators: -

また、オプション --vertex にvertex IDを指定して実行すると、指定したvertexの情報のみを表示します。

$ asakusa list plan m3bp.example.summarizeSales --vertex v3
label: @MasterJoin:CategorySummaryOperator.joinItemInfo
blockers: {v1, v2}
operators:
    com.example.operator.CategorySummaryOperator#setErrorMessage(@Update)
    com.example.operator.CategorySummaryOperator#joinItemInfo(@MasterJoin)

Hint

vertex IDはバッチアプリケーション実行時のログやスタックトレースなどに含まれます。これらの情報と plan コマンドの出力内容、または後述の asakusa generate dot plan コマンドによって生成する実行計画グラフの内容を付き合わせることで、ログやスタックトレースに対応する演算子の処理や、その前後に実行される演算子の処理をある程度絞り込むことができます。

asakusa generate

generate は、バッチアプリケーションのDSL情報から様々なリソースを生成します。 generate のサブコマンド一覧を以下に示します。

generate サブコマンド

サブコマンド

説明

asakusa generate dot

グラフ表示ツール Graphviz 3 向けの dot スクリプトを生成する

asakusa generate ddl

DDLスクリプトを生成する

3

http://www.graphviz.org/

asakusa generate dot

dot はバッチアプリケーションのDSL情報からグラフ表示ツール Graphviz 向けの dot スクリプトを生成します。 dot のサブコマンド一覧を以下に示します。

dot サブコマンド

サブコマンド

説明

jobflow

ジョブフローグラフを dot スクリプトとして生成する

operator

演算子グラフを dot スクリプトとして生成する

plan

Batch DSLコンパイルによって生成される実行計画グラフを dot スクリプトとして生成する

書式

asakusa generate dot {jobflow|operator|plan} [options] batch-id

説明

指定したバッチIDに対応するバッチアプリケーションのDSL情報に基づいて、 dot スクリプトを生成します。

生成した dot スクリプトは Graphviz の dot コマンドなどを使用してPDFや画像ファイルに変換したり、デスクトップ環境のクライアントツールから表示することができます。

オプション

dot サブコマンドで使用できる主なオプションを以下に示します。利用可能なすべてのオプションは、コマンドのヘルプを参照してください。

-e, --encoding encoding

生成するスクリプトの文字セットエンコーディングを指定する。

デフォルトでは環境の標準エンコーディングを使用する。

Hint

Graphvizで日本語を扱う場合、UTF-8を指定してスクリプトを生成する必要があります。 Windows環境など、標準エンコーディングがUTF-8以外の環境でスクリプトを生成する場合、このオプションをスクリプトの出力先を指定する -o オプションと合わせて指定します。

-o, --output file

生成したスクリプトを指定したファイルパスに保存する。デフォルトでは標準出力にスクリプトを出力する。

--flow-part, --flowpart flowpart-classname

( operator サブコマンドのみ )指定したフロー部品クラス名に対応するフロー部品の演算子グラフを生成する。

--flow, --jobflow flow-id

( operator サブコマンドのみ )指定したフローIDに対応するジョブフローの演算子グラフを生成する。

使用例

以下はバッチアプリケーションの演算子グラフを生成し、 dot コマンドでPDFに変換する例です。

$ asakusa generate dot operator m3bp.example.summarizeSales -o build/operator-graph.dot
$ dot -Tpdf -o build/operator-graph.pdf build/operator-graph.dot

以下はバッチアプリケーションの実行計画グラフを演算子情報を付加して生成し、dot コマンドで画像ファイルに変換する例です。

$ asakusa generate dot plan m3bp.example.summarizeSales --show-operator -o build/plan-graph.dot
$ dot -Tpng -o build/plan-graph.png build/plan-graph.dot

Hint

実行計画グラフの各Vertexの上部にはvertex IDが表示されます ( v0 , v1 といった値が表示されている部分 )。 vertex IDについては asakusa list の asakusa list plan サブコマンドの説明を参考にしてください。

asakusa generate ddl

ddl はバッチアプリケーションのDSL情報からDDLスクリプトを生成する ddl のサブコマンド一覧を以下に示します。

ddl サブコマンド

サブコマンド

説明

hive

Direct I/O Hive のDSL情報からHive DDLスクリプトを生成する。

書式

asakusa generate ddl hive [options] batch-id

説明

指定したバッチIDに対応するバッチアプリケーションが使用する、拡張属性を持つDMDLスクリプト情報から各種DDLスクリプトを生成します。現時点では、 Direct I/O Hive 向けのHive DDLスクリプトを生成する hive サブコマンドのみが使用できます。

hive サブコマンドは指定したバッチIDに対応するバッチアプリケーションのDMDLスクリプト情報に基づいてHive用のDDLスクリプトを生成します。

オプション

ddl hive サブコマンドで使用できる主なオプションを以下に示します。利用可能なすべてのオプションは、コマンドのヘルプを参照してください。

-e, --encoding encoding

生成するスクリプトの文字セットエンコーディングを指定する。

デフォルトでは環境の標準エンコーディングを使用する。

Hint

Hiveスクリプトのコメントなどに日本語を含める場合、UTF-8を指定してスクリプトを生成する必要があります。 Windows環境など、標準エンコーディングがUTF-8以外の環境でスクリプトを生成する場合、このオプションをスクリプトの出力先を指定する -o オプションと合わせて指定します。

-o, --output file

生成したスクリプトを指定したファイルパスに保存する。デフォルトでは標準出力にスクリプトを出力する。

--database database-name

生成する CRATE TABLE 文のテーブル名の前にデータベース名を付与する。

--external

CREATE EXTERNAL TABLE キーワードを使用して、テーブルをExtrnal Tableとして生成する。

-L, --location base-path-prefix=fs-path-pretix...

生成する CREATE TABLE 文に LOCATION キーワード (テーブルに対応するデータファイルを配置するファイルシステム上のパス) を追加する。

オプションのパラメータには ベースパス=ファイルシステムパス という形式で、ベースパスに対するファイルシステムのマッピング情報を指定する。ファイルシステムパスはURI形式で記述した場合、指定したスキーマに対応するファイルシステムが使用される(例 hdfs:///user/asakusa/directio )。スキーマ部分を省略した場合、環境のデフォルトファイルシステムが使用される(例 /user/asakusa/directio )。

このオプションは以下のように複数指定が可能。

asakusa generate ddl hive m3bp.example.batch -L/=/var -L/tmp=/tmp

また、ベースパスにバッチ引数を使用する場合は以下のように指定する。

asakusa generate ddl hive m3bp.example.batch -L'${input}'=/path/to/input -L'${output}'=/path/to/output

--table pattern

指定した正規表現にマッチするテーブルに対してのみDDLスクリプトを生成する。

使用例

以下はHive DDLスクリプトを生成する例です。

asakusa generate ddl hive spark.example.summarizeSales --location /=/user/asakusa/directio/hive -o build/hive-ddl.sql

asakusa version

version は、環境にインストールまたはデプロイされているAsakusa Frameworkのバージョンを表示します。

書式

asakusa version [options]

使用例

version を標準のオプションで実行すると、Asakusa Frameworkのバージョンを表示します。

$ asakusa version
0.10.0

version を詳細オプション付きで実行すると、環境で使用される環境変数やJavaに関する情報も表示します。

$ asakusa version -v
0.10.0
ASAKUSA_HOME: /home/asakusa/asakusa
Hadoop: /usr/local/lib/hadoop/bin/hadoop
java.version: 1.8.0_121
java.vendor: Oracle Corporation

開発環境の整備 - Asakusa Gradle Plugin

Asakusa Frameworkによる開発を行うための開発環境の構築について説明します。

Asakusa Framework開発環境の新規構築

Asakusa Frameworkの開発環境(OSやAsakusa Frameworkが利用するソフトウェアも含めた開発環境)を新規に構築する場合は、 Asakusa Framework スタートガイド や Jinrikisha (人力車) - Asakusa Framework Starter Package - [https://docs.asakusafw.com/jinrikisha/ja/html/index.html] を参照してください。

アプリケーション開発プロジェクトの構築と管理

アプリケーション開発用のプロジェクトの作成やビルド、ライブラリの管理などに関するドキュメントです。

Asakusa Gradle Plugin ユーザーガイド

Asakusa Gradle Plugin リファレンス

マイグレーション

開発環境マイグレーションガイド

Asakusa Gradle Plugin マイグレーションガイド

Asakusa Gradle Plugin バージョン 0.10系 の変更点

Asakusa Gradle Plugin バージョン 0.9系 の変更点

Asakusa Gradle Plugin バージョン 0.8系 の変更点

過去の開発環境マイグレーションガイド

プラットフォーム関連

特定のプラットフォームでAsakusa Frameworkを利用することに関するドキュメントです。

開発環境のJava

IntelliJ IDEAの利用

関連するドキュメント

Asakusa Gradle Plugin ユーザーガイド

Asakusa Gradle Plugin リファレンス

開発環境マイグレーションガイド

Asakusa Gradle Plugin マイグレーションガイド

Asakusa Gradle Plugin バージョン 0.10系 の変更点

Asakusa Gradle Plugin バージョン 0.9系 の変更点

Asakusa Gradle Plugin バージョン 0.8系 の変更点

過去の開発環境マイグレーションガイド

開発環境のJava

IntelliJ IDEAの利用

Asakusa Gradle Plugin:非推奨機能

Asakusa Gradle Plugin ユーザーガイド

この文書では、Gradle [http://www.gradle.org/]にAsakusa Framework を使ったアプリケーションの開発やデプロイを行うための機能を追加するAsakusa Gradle Pluginについて説明します。

概要

Asakusa Gradle Pluginは、Asakusa Framework用のGradle拡張プラグイン群です。このプラグインを利用することで、Gradleを利用してAsakusa Framework を使ったアプリケーションの開発やデプロイを行うことができます。

利用環境

Asakusa Gradle Pluginを利用するにはJava(JDK)がインストールされている必要があります。これらの導入方法については、 Asakusa Framework スタートガイド - 開発環境の準備 などを参考にしてください。

なお、Gradleのインストールについては、本書では Gradleラッパー [http://www.gradle.org/docs/current/userguide/gradle_wrapper.html] と呼ばれるGradleを利用するためのコマンドを使う方法を推奨しています。この方法に沿ってGradleを利用する場合は前もってGradleをインストールする必要はありません。詳しくは後述の Asakusa Gradle Pluginの導入 を参考にしてください。

Gradleについて

Gradle [http://www.gradle.org/] はオープンソースプロジェクトとして開発されている様々なプラットフォームに対応したビルドシステムです。シンプルかつ拡張性の高いビルド定義を行うためのDSLやプラグイン機構を持ち、他のビルドシステムとの連携を含む様々な方式に対応した依存性管理のメカニズムを有しているなど多くの特徴を持っています。

Gradleに関する詳しい情報は、以下のドキュメントなどを参考にしてください。

Gradle Documentation [http://www.gradle.org/documentation] (Gradleの公式ドキュメントサイト)

Gradle 日本語ドキュメント [http://gradle.monochromeroad.com/docs/] (公式ドキュメントの翻訳サイト)

関連プロダクト

Shafu

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

Shafu - Asakusa Gradle Plug-in Helper for Eclipse - [https://docs.asakusafw.com/jinrikisha/ja/html/shafu.html]

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ラッパー [http://www.gradle.org/docs/current/userguide/gradle_wrapper.html] と呼ばれるGradleを利用するコマンドが含まれます。このコマンドを利用することで、Gradle自体の導入設定は不要となり、すぐにこのプロジェクト上で開発を始めることができます。

現在のところ、プロジェクトテンプレートは利用するプラットフォームに応じた初期設定が導入された複数種類のテンプレートを公開しています。

2)は、テンプレートを使用せずフルスクラッチでビルドスクリプトの定義やプロジェクトレイアウトを作成する方法です。この方法はGradleやAsakusa Gradle Pluginの利用に精通している必要がありますが、既存プロジェクトのマイグレーションなどで個別に設定を行う必要がある場合などでは、こちらの方法を検討してください。

以下では、1)のAsakusa Gradle Plugin 用プロジェクトテンプレートを利用した導入方法を解説します。 2)については、 Asakusa Gradle Plugin リファレンス を参照してください。

プロジェクトテンプレートのダウンロード

プロジェクトテンプレートは、以下リンクからダウンロードします。

プロジェクトテンプレートのダウンロード

プロジェクトテンプレート

説明

asakusa-spark-template-0.10.3.tar.gz [http://www.asakusafw.com/download/gradle-plugin/asakusa-spark-template-0.10.3.tar.gz]

Asakusa on Spark を利用するプロジェクトテンプレート

asakusa-m3bp-template-0.10.3.tar.gz [http://www.asakusafw.com/download/gradle-plugin/asakusa-m3bp-template-0.10.3.tar.gz]

Asakusa on M3BP を利用するプロジェクトテンプレート

asakusa-mapreduce-template-0.10.3.tar.gz [http://www.asakusafw.com/download/gradle-plugin/asakusa-mapreduce-template-0.10.3.tar.gz]

Asakusa on MapReduce を利用するプロジェクトテンプレート

また、Asakusa Frameworkの サンプルプログラム集 (GitHub) [http://github.com/asakusafw/asakusafw-examples] では、サンプルアプリケーションのソースコード一式を含むサンプルアプリケーションプロジェクトを公開しています。

プロジェクトの配置

ダウンロードしたプロジェクトテンプレートのアーカイブを展開すると、プロジェクトテンプレート名をディレクトリ名に持つプロジェクトファイル一式が作成されます。このディレクトリを開発するアプリケーションを示すプロジェクト名に変更して、作業用ディレクトリに配置してください。サンプルアプリケーションを利用する場合も同様です。

以降本書では、ビルドの流れを解説するために サンプルプログラム集 (GitHub) [http://github.com/asakusafw/asakusafw-examples] に公開されているサンプルアプリケーションプロジェクト example-basic-spark を使って説明します。このサンプルアプリケーションは、Asakusa on Sparkのプロジェクトテンプレートをベースにして作成されています。

ここでは、ダウンロードしたサンプルアプリケーションプロジェクト example-basic-spark を $HOME/workspace に配置したものとします。

cd ~/Downloads
curl -OL https://github.com/asakusafw/asakusafw-examples/archive/0.10.3.tar.gz
tar xf 0.10.3.tar.gz
cp -a asakusafw-examples-0.10.3/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を利用するための設定が記述されています。

build.gradle

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.3'
    }
}

apply plugin: 'asakusafw-sdk'
apply plugin: 'asakusafw-organizer'
apply plugin: 'asakusafw-spark'
apply plugin: 'eclipse'

プロジェクトテンプレートに含まれるビルドスクリプトには、以下の機能を利用するための設定があらかじめ定義されています。

Asakusa DSL

Asakusa Data Model (DMDL)

テストドライバ

Direct I/O

WindGate

ソースディレクトリ

プロジェクトのソースディレクトリは大きくアプリケーション本体のコードを配置する src/main ディレクトリと、アプリケーションのテスト用のコードを配置する src/test ディレクトリに分かれます。

それぞれのディレクトリ/ファイルの構成を以下に示します。

プロジェクトレイアウト - src/main

ファイル/ディレクトリ

説明

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

ファイル/ディレクトリ

説明

src/test/java

Asakusa DSLのテスト用ソースディレクトリ

src/test/resources

プロジェクトのテスト用リソースディレクトリ

src/test/resources/logback-test.xml

ビルド/テスト実行時に使用されるログ定義ファイル

ビルドディレクトリ

プロジェクトのビルドディレクトリはGradleの各プラグインが提供するタスクの実行に対応したビルド成果物が作成されます。デフォルト設定のビルドディレクトリは build です。

ビルドディレクトリの主なディレクトリ/ファイルの構成を以下に示します 3 。

プロジェクトレイアウト - build

ファイル/ディレクトリ

生成タスクの例

説明

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

M³ 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のメニューから File ‣ Import ‣ General ‣ Existing Projects into Workspace を選択し、プロジェクトディレクトリを指定します。

ビルド設定のカスタマイズ

ビルドに関する設定をカスタマイズするには、基本的にはGradleのビルドスクリプトである build.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.3'
    }
}

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
}

標準プロジェクトプロパティ

標準的なプロジェクト情報は、以下のようにビルドスクリプトのトップレベルの階層に定義します。

build.gradle

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 ブロックが指定されています。ブロック内には複数のプロパティを指定することができます。

build.gradle

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 から始まるブロックは、デプロイメントアーカイブの構成情報を管理するプロファイルに関する設定です。プロファイルについては後述の プロファイルの管理 で詳しく説明します。

build.gradle

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ライブラリを追加しています。

build.gradle

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 を定義する例です。

build.gradle

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 [https://docs.asakusafw.com/0.10.3/release/gradle-plugins/com/asakusafw/gradle/plugins/AsakusafwOrganizerProfile.html] が提供します。

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 M³BP 用のプラグイン asakusafw-m3bp を追加しています。

build.gradle

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 M³BP コンパイラを無効にしています。この設定により、 assemble タスクの実行時に Asakusa on M³BP コンパイラのコンパイル処理がスキップされます。

build.gradle

asakusafwOrganizer {
    spark.enabled true
    m3bp.enabled false
}

これらの記述を省略した場合、各DSLコンパイラの利用は有効 ( true ) になります。

これらの設定はプロファイル単位でも設定することができます。

バッチコンパイル対象のフィルタリング

標準の構成では、バッチアプリケーションのコンパイルやデプロイメントの構成時にはプロジェクトに含まれる全てのバッチクラスがコンパイルの対象となりますが、ビルドスクリプトの定義やコマンドラインの指定で、一部のバッチクラスのみをコンパイルすることができます。

ビルドスクリプトの指定によるフィルタリング

ビルドスクリプトの構成で有効となっている各DSLコンパイラに対して、コンパイル対象のバッチクラスを include/exclude することができます。

以下、ビルドスクリプトの設定例です。

build.gradle

asakusafw {
    spark {
        exclude 'com.example.batch.Hoge'
    }
    m3bp {
        include 'com.example.batch.Hoge'
    }
}

上記の設定例では、Asakusa on Sparkコンパイラに対してはバッチクラス com.example.batch.Hoge を除外しその他のバッチクラスを全て含めるよう指定しています。また Asakusa on M³BP コンパイラに対してはバッチクラス 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.3 では、 TestTookTask は試験的機能として提供しています。

TestToolTask 7 を使うことで、テストドライバーやバッチテストランナーが持つ機能を組み合わせてGradleのタスクとして実行することができます。

See also

テストツールタスクの利用例は テストドライバーユーザーガイド - テストツールタスク を参照してください。

7

com.asakusafw.gradle.tasks.TestToolTask [https://docs.asakusafw.com/0.10.3/release/gradle-plugins/com/asakusafw/gradle/tasks/TestToolTask.html]

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-name database-name

生成する CRATE TABLE 文のテーブル名の前にデータベース名を付与する

指定がない場合は データベース名は未指定

--include regex-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 を参照してください。

Asakusa Gradle Plugin リファレンス

この文書では、Asakusa Gradle Pluginが提供する機能とインターフェースについて個々に解説します。

リポジトリ

Asakusa Gradle PluginはAsakusa FrameworkのMavenリポジトリ( http://asakusafw.s3.amazonaws.com/maven/releases )に以下のMavenアーティファクトが登録されています。

Asakusa Gradle PluginのMavenアーティファクト

グループID

アーティファクトID

説明

com.asakusafw.gradle

asakusa-distribution

ディストリビューションプラグイン ( ディストリビューションプラグインの利用 )。

ディストリビューションプラグインの利用

Asakusa Gradle Pluginを利用する場合には、プロジェクトに対してディストリビューションプラグイン com.asakusafw.gradle:asakusa-distribution を有効にします。

ディストリビューションプラグインはAsakusa Frameworkのリリース時に動作検証を行った各サブプロジェクトの組み合わせによる Gradle Pluginのバージョンを自動的に適用し、これらを単一のバージョンで利用できるようにします。将来サブプロジェクトが追加された場合や構成が変更になった場合にも、マイグレーションの手順がシンプルになります。

例えば、ディストリビューションプラグインのバージョン 0.10.0 は以下のGradle Pluginを自動的に適用します。

com.asakusafw:asakusa-gradle-plugins:0.10.0

com.asakusafw.spark:asakusa-spark-gradle:0.5.0

com.asakusafw.m3bp:asakusa-m3bp-gradle:0.3.0

See also

Gradle Pluginによってアプリケーションプロジェクトに適用される各コンポーネントのバージョンを確認する方法は、後述の バージョンの確認 を参照してください。

使用方法

アプリケーションプロジェクトからAsakusa Gradle Pluginを利用する場合、ビルドスクリプト build.gradle の buildscript ブロック内に利用するAsakusa Gradle PluginのMavenアーティファクトと、これを取得するためのMavenリポジトリのURLを定義します。

以下は、ビルドスクリプトにディストリビューションプラグインを適用する例です。

build.gradle

buildscript {
    repositories {
        maven { url 'http://asakusafw.s3.amazonaws.com/maven/releases' }
    }
    dependencies {
        classpath group: 'com.asakusafw.gradle', name: 'asakusa-distribution', version: '0.10.3'
    }
}

Asakusa Gradle Plugin 一覧

Asakusa Gradle Pluginはいくつかのプラグインから構成されています。以下にその一覧を示します。

Asakusa Gradle Plugin 一覧

プラグインID

プラグイン名

自動適用

説明

asakusafw-sdk

Batch Application Plugin

java

Asakusa Frameworkのバッチアプリケーションを開発を行うための支援機能をプロジェクトに追加する。

asakusafw-organizer

Framework Organizer Plugin

-

Asakusa Frameworkを利用した開発環境の構築や、運用環境へのデプロイを行うための援機能を提供する。

また、以下のプラグインは上記のプラグインに対して特定プラットフォームやコンポーネントを利用するための機能を追加します。

Asakusa Gradle Plugin 拡張プラグイン一覧

プラグインID

プラグイン名

自動適用

説明

asakusafw-mapreduce

Asakusa on MapReduce Plugin

-

MapReduce向けのバッチアプリケーションを生成、実行するための機能を導入する。

asakusafw-spark

Asakusa on Spark Plugin

-

Spark向けのバッチアプリケーションを生成、実行するための機能を導入する。

asakusafw-m3bp

Asakusa on M³BP Plugin

-

M³ for Batch Processing 向けのバッチアプリケーションを生成、実行するための機能を導入する。

asakusafw-vanilla

Asakusa Vanilla Plugin

-

Asakusa Vanilla 向けのバッチアプリケーションを生成、実行するための機能を導入する。

使用方法

Asakusa Gradle Pluginの各プラグインを使うためには、ビルドスクリプトに apply plugin: <プラグインID> という設定を含めます。以下、設定例です。

build.gradle

apply plugin: 'asakusafw-sdk'
apply plugin: 'asakusafw-organizer'
apply plugin: 'asakusafw-spark'
apply plugin: 'asakusafw-m3bp'

バージョンの確認

アプリケーションプロジェクトで使用する各コンポーネントのバージョンを表示するには、asakusaVersion タスクを実行します。

./gradlew asakusaVersion

asakusaVersion タスクはビルドスクリプトの設定を解析し、以下のようにプロジェクトで利用するコンポーネントのバージョンを表示します。

> Task :asakusaVersions
Asakusa Gradle Plug-ins: 0.10.0
Asakusa SDK: 0.10.0
JVM: 1.8
Asakusa Language: 0.5.0
Asakusa Vanilla: 0.5.0
Asakusa on Spark: 0.5.0
Spark: 2.2.0
Asakusa on M3BP: 0.3.0

Batch Application Plugin

Batch Application Plugin は、Asakusa Framework の バッチアプリケーション開発を行うための支援機能を提供します。

Batch Application Plugin はAsakusa Framework の バッチアプリケーションプロジェクトに対して、以下のような機能を提供します。

DMDLスクリプトからデータモデルクラスを生成するタスクの提供

Gradle標準のJavaコンパイルタスクに対して、Operator DSLコンパイラによる演算子実装クラス、演算子ファクトリクラスの生成を行うための設定を追加

Asakusa DSLとして記述したJavaソースファイル一式に対して、Batch DSLコンパイラによるバッチアプリケーション実行モジュールの生成を行うタスクの提供

テストドライバーを利用したテストケースを作成するためのテストデータ定義シートのテンプレートファイルを生成するタスクの提供

Gradle標準のEclipseのタスクに対して、Asakusa Framework用の設定を追加

Note

このプラグインはGradleが提供するJavaプラグインやEclipseプラグインを拡張して作成されています。

タスク

Batch Application Plugin は、以下のタスクをプロジェクトに追加します。

Batch Application Plugin - タスク

タスク名

プラグイン

型

説明

asakusaVersion

asakusafw-sdk

-

プロジェクトが利用する各コンポーネントのバージョンを表示する

asakusaUpgrade

asakusafw-sdk

-

プロジェクトが利用するGradleコンポーネントをアップデートする

compileDMDL

asakusafw-sdk

CompileDmdlTask 1

DMDLコンパイラを使ってデータモデルクラスを生成する

compileBatchapp

asakusafw-sdk

CompileBatchappTask 2

プロジェクトのビルド構成に基づくBatch DSLコンパイラを使ってバッチアプリケーションを生成する

jarBatchapp

asakusafw-sdk

Jar

バッチアプリケーションアーカイブを生成する

generateTestbook

asakusafw-sdk

GenerateTestbookTask 3

テストデータ定義シートを生成する

generateHiveDDL

asakusafw-sdk

GenerateHiveDdlTask 4

DMDLからHive用のDDLファイルを生成する

1

com.asakusafw.gradle.tasks.CompileDmdlTask [https://docs.asakusafw.com/0.10.3/release/gradle-plugins/com/asakusafw/gradle/tasks/CompileDmdlTask.html]

2

com.asakusafw.gradle.tasks.CompileBatchappTask [https://docs.asakusafw.com/0.10.3/release/gradle-plugins/com/asakusafw/gradle/tasks/CompileBatchappTask.html]

3

com.asakusafw.gradle.tasks.GenerateTestbookTask [https://docs.asakusafw.com/0.10.3/release/gradle-plugins/com/asakusafw/gradle/tasks/GenerateTestbookTask.html]

4

com.asakusafw.gradle.tasks.GenerateHiveDdlTask [https://docs.asakusafw.com/0.10.3/release/gradle-plugins/com/asakusafw/gradle/tasks/GenerateHiveDdlTask.html]

また、Batch Application Pluginは以下のタスクに対してタスク依存関係を追加します。

Batch Application Plugin - タスク依存関係

タスク名

依存先

compileJava

compileDMDL

compileBatchapp

classes

jarBatchapp

compileBatchapp

assemble

compileBatchapp

依存関係の管理

Batch Application Plugin は、以下の依存関係設定をプロジェクトに追加します。

Batch Application Plugin - 依存関係設定

名前

説明

provided

アプリケーションのビルド時に依存するが、アプリケーションの実行時には実行環境に配置されている実体(jarファイルなど)を使用する依存関係設定

embedded

プロジェクトディレクトリ配下に実体(jarファイルなど)を配置する依存関係設定

リポジトリ

Batch Application Plugin は、以下のリポジトリをプロジェクトに追加します。

Batch Application Plugin - リポジトリ

名前/URL

説明

http://repo1.maven.org/maven2/

Mavenのセントラルリポジトリ

http://asakusafw.s3.amazonaws.com/maven/releases

Asakusa Frameworkのリリース用Mavenリポジトリ

http://asakusafw.s3.amazonaws.com/maven/snapshots

Asakusa Frameworkのスナップショット用Mavenリポジトリ

Tip

プロジェクトに固有のリポジトリを追加する場合、ビルドスクリプトのプラグイン定義 ( apply plugin: xxx ) 位置の前にリポジトリ定義を追加すると、プラグインが標準で設定するリポジトリよりも優先して使用されます。開発環境でインハウスリポジトリを優先して利用したい場合などは、プラグイン定義の前にリポジトリ定義を追加するとよいでしょう。

規約プロパティ

Batch Application Pluginの規約プロパティはビルドスクリプトから 参照名 asakusafw でアクセスできます 5 。この規約オブジェクトは以下のプロパティを持ちます。

Batch Application Plugin - 規約プロパティ ( asakusafw ブロック )

プロパティ名

型

デフォルト値

説明

maxHeapSize

String

1024m

プラグインが実行するJavaプロセスの最大ヒープサイズ

logbackConf

String

src/${project.sourceSets.test.name}/resources/logback-test.xml

プロジェクトのLogback設定ファイル 6

basePackage

String

${project.group}

プラグインの各タスクでJavaソースコードの生成時に指定する基底Javaパッケージ

5

これらのプロパティは規約オブジェクト com.asakusafw.gradle.plugins.AsakusafwPluginConvention [https://docs.asakusafw.com/0.10.3/release/gradle-plugins/com/asakusafw/gradle/plugins/AsakusafwPluginConvention.html] が提供します。

6

Logback設定ファイルの詳細は次のドキュメントを参照してください: http://logback.qos.ch/manual/configuration.html

コアプロパティ

Asakusa Frameworkコアに関する規約プロパティは、 asakusafw ブロック内の参照名 core でアクセスできます 7 。この規約オブジェクトは以下のプロパティを持ちます。

Batch Application Plugin - コアプロパティ ( core ブロック )

プロパティ名

型

デフォルト値

説明

version

String

コアライブラリのバージョン

コアライブラリのバージョンを保持する。この値は変更不可。

7

これらのプロパティは規約オブジェクト com.asakusafw.gradle.plugins.AsakusafwPluginConvention.CoreConfiguration [https://docs.asakusafw.com/0.10.3/release/gradle-plugins/com/asakusafw/gradle/plugins/AsakusafwPluginConvention.CoreConfiguration.html] が提供します。

DMDLプロパティ

DMDLに関する規約プロパティは、 asakusafw ブロック内の参照名 dmdl でアクセスできます 8 。この規約オブジェクトは以下のプロパティを持ちます。

Batch Application Plugin - DMDLプロパティ ( dmdl ブロック )

プロパティ名

型

デフォルト値

説明

dmdlEncoding

String

UTF-8

DMDLスクリプトのエンコーディング

dmdlSourceDirectory

String

src/${project.sourceSets.main.name}/dmdl

DMDLスクリプトのソースディレクトリ

8

これらのプロパティは規約オブジェクト com.asakusafw.gradle.plugins.AsakusafwPluginConvention.DmdlConfiguration [https://docs.asakusafw.com/0.10.3/release/gradle-plugins/com/asakusafw/gradle/plugins/AsakusafwPluginConvention.DmdlConfiguration.html] が提供します。

データモデル生成プロパティ

データモデル生成に関する規約プロパティは、 asakusafw ブロック内の参照名 modelgen でアクセスできます 9 。この規約オブジェクトは以下のプロパティを持ちます。

Batch Application Plugin - データモデル生成プロパティ ( modelgen ブロック )

プロパティ名

型

デフォルト値

説明

modelgenSourcePackage

String

${asakusafw.basePackage}.modelgen

データモデルクラスに使用されるパッケージ名

modelgenSourceDirectory

String

${project.buildDir}/generated-sources/modelgen

データモデルクラスのソースディレクトリ

9

これらのプロパティは規約オブジェクト com.asakusafw.gradle.plugins.AsakusafwPluginConvention.ModelgenConfiguration [https://docs.asakusafw.com/0.10.3/release/gradle-plugins/com/asakusafw/gradle/plugins/AsakusafwPluginConvention.ModelgenConfiguration.html] が提供します。

Javaコンパイラプロパティ

Javaコンパイラ関する規約プロパティは、 asakusafw ブロック内の参照名 javac でアクセスできます 10 。この規約オブジェクトは以下のプロパティを持ちます。

Batch Application Plugin - Javaコンパイラプロパティ ( javac ブロック )

プロパティ名

型

デフォルト値

説明

annotationSourceDirectory

String

${project.buildDir}/generated-sources/annotations

アノテーションプロセッサが生成するJavaソースの出力先

processorOption

Object

アノテーションプロセッサによる生成処理に必要な最低限のもの

アノテーションプロセッサに対するオプションを <key>, <value> の形式で指定する

processorOptions

Map<?, ?>

アノテーションプロセッサによる生成処理に必要な最低限のもの

アノテーションプロセッサに対するオプションをMap形式で指定する

sourceEncoding

String

UTF-8

プロジェクトのソースファイルのエンコーディング

sourceCompatibility

JavaVersion。Stringも利用可能。 例： '1.8'

1.8

Javaソースのコンパイル時に使用するJavaバージョン互換性

targetCompatibility

JavaVersion。Stringも利用可能。例： '1.8'

1.8

クラス生成のターゲットJavaバージョン

10

これらのプロパティは規約オブジェクト com.asakusafw.gradle.plugins.AsakusafwPluginConvention.JavacConfiguration [https://docs.asakusafw.com/0.10.3/release/gradle-plugins/com/asakusafw/gradle/plugins/AsakusafwPluginConvention.JavacConfiguration.html] が提供します。

MapReduceプロパティ

Spark DSLコンパイラに関する規約プロパティは、 asakusafw ブロック内の参照名 mapreduce でアクセスできます。

この規約オブジェクトについては、Asakusa on Sparkの以下のドキュメントを参照してください。

Asakusa on MapReduce リファレンス - Batch Application Plugin ( asakusafw ) への拡張

Sparkプロパティ

Spark DSLコンパイラに関する規約プロパティは、 asakusafw ブロック内の参照名 spark でアクセスできます。

この規約オブジェクトについては、Asakusa on Sparkの以下のドキュメントを参照してください。

Asakusa on Spark リファレンス - Batch Application Plugin ( asakusafw ) への拡張

M3BPプロパティ

M³BP DSLコンパイラに関する規約プロパティは、 asakusafw ブロック内の参照名 m3bp でアクセスできます。

この規約オブジェクトについては、 Asakusa on M³BP の以下のドキュメントを参照してください。

Asakusa on M3BPリファレンス - Batch Application Plugin ( asakusafw ) への拡張

テストツールプロパティ

テストツールに関する規約プロパティは、 asakusafw ブロック内の参照名 testtools でアクセスできます 11 。この規約オブジェクトは以下のプロパティを持ちます。

Batch Application Plugin - テストツールプロパティ ( testtools ブロック )

プロパティ名

型

デフォルト値

説明

testDataSheetFormat

String

ALL

テストデータ定義シートのフォーマット 12

testDataSheetDirectory

String

${project.buildDir}/excel

テストデータ定義シートの出力先

11

これらのプロパティは規約オブジェクト com.asakusafw.gradle.plugins.AsakusafwPluginConvention.TestToolsConfiguration [https://docs.asakusafw.com/0.10.3/release/gradle-plugins/com/asakusafw/gradle/plugins/AsakusafwPluginConvention.TestToolsConfiguration.html] が提供します。

12

テストデータ定義シートのフォーマット指定値は、 Excelによるテストデータ定義 - formatオプション を参照してください。

SDKプロパティ

アプリケーションSDKライブラリ 13 に関する規約プロパティは、 asakusafw ブロック内の参照名 sdk でアクセスできます 14 。この規約オブジェクトは以下のプロパティを持ちます。

Batch Application Plugin - SDKプロパティ ( sdk ブロック )

プロパティ名

型

デフォルト値

説明

core

Object

true

この値をtrueにするとコアライブラリ(実行ライブラリやDSL語彙など)を依存ライブラリに追加する。 true または false を指定可能。

dmdl

Object

true

この値をtrueにするとDMDLライブラリ(DMDLコンパイラなど)を依存ライブラリに追加する。 true または false を指定可能。

operator

Object

true

この値をtrueにするとOprator DSLライブラリ(Operator DSLコンパイラなど)を依存ライブラリに追加する。 true または false を指定可能。

testing

Object

true

この値をtrueにするとテストツールライブラリ(テストドライバなど)を依存ライブラリに追加する。 true または false を指定可能。

testkit

Object

vanilla

テストドライバで利用する実行エンジンを指定する。 vanilla (Asakusa Vanilla) , mapreduce (Hadoop MapReduce) , mapreduce-emulation (エミュレーションモード) を指定可能 15 。

directio

Object

true

この値をtrueにするとDirect I/Oライブラリを依存ライブラリに追加する。 true または false を指定可能。

windgate

Object

true

この値をtrueにするとWindGateライブラリを依存ライブラリに追加する。 true または false を指定可能。

yaess

Object

true

この値をtrueにするとバッチアプリケーションのコンパイル時にYAESSのワークフロースクリプトを追加する。 true または false を指定可能。

hive

Object

false

この値をtrueにするとDirect I/O Hiveライブラリ、および標準の設定に基づくバージョンのHive実行ライブラリを依存ライブラリに追加する。また、リスト形式でHive実行ライブラリのバージョンを指定することで、任意のバージョンのHive実行ライブラリを依存ライブラリに追加する 16 。 true または false 、もしくは java.util.List を指定可能。

13

アプリケーションSDKライブラリについては、 Asakusa Gradle Plugin ユーザーガイド - 依存ライブラリの管理 も参照してください。

14

これらのプロパティは規約オブジェクト com.asakusafw.gradle.plugins.AsakusafwSdkExtension [https://docs.asakusafw.com/0.10.3/release/gradle-plugins/com/asakusafw/gradle/plugins/AsakusafwSdkExtension.html] が提供します。

15

標準の設定以外の実行エンジンの利用は非推奨です。

16

設定方法の例や詳細については、 Direct I/O Hive を参照してください。

Eclipse Pluginの拡張

Batch Application Plugin は Gradleが提供するEclipse Pluginのタスクに対して、以下のようなEclipseプロジェクトの追加設定を行います。

OperatorDSLコンパイラを実行するためのAnnotation Processorの設定

Javaのバージョンやエンコーディングに関する設定

また、Batch Application Pluginが設定する規約プロパティの情報を .settings/com.asakusafw.asakusafw.prefs に出力します。

GradleからEclipseプロジェクト用の定義ファイルを生成する方法については、 Eclipse定義ファイルの作成 を参照してください。

IntelliJ IDEAの利用

Asakusa FrameworkのアプリケーションプロジェクトはIntelliJ IDEAのGradleプロジェクトとして利用することもできます。

詳しくは、 IntelliJ IDEAの利用 を参照してください。

Attention

Asakusa Framework バージョン 0.10.3 では、過去バージョンで提供していた IDEA Pluginの拡張と idea タスクの利用は非推奨となりました。 IntelliJ IDEAのバージョンによっては、これらの機能は正しく動作しません。

IntelliJ IDEAを利用する場合、 IntelliJ IDEAの利用 のドキュメント内容に従って利用してください。

Framework Organizer Plugin

Framework Organizer Plugin は、Asakusa Framework を 利用した開発環境の構築や、運用環境に対するデプロイモジュールの構成管理機能を提供します。

Framework Organizer Plugin が提供する機能には次のようなものがあります。

Asakusa Frameworkのデプロイメントモジュールの構成を定義し、デプロイメントアーカイブを生成するタスクの提供

Asakusa Frameworkが提供する各コンポーネントの設定や拡張モジュールの利用などを環境ごとに設定するプロファイル管理機能の提供

Asakusa Frameworkを開発環境へインストールするタスクの提供

タスク

Framework Organizer Plugin は、以下のタスクを定義します。

Framework Organizer Plugin - タスク

タスク名

依存先

型

説明

assembleAsakusafw

-

Task

運用環境向けのデプロイメント構成を持つデプロイメントアーカイブを生成する

installAsakusafw

-

Task

開発環境向けのデプロイメント構成をローカル環境にインストールする

Note

Framework Organizer Pluginは上記のタスク一覧の他に、プラグイン内部で attach から始まるタスクを生成し利用します。

リポジトリ

Framework Organizer Plugin は、 Batch Application Plugin のリポジトリ定義と共通の設定を使用します。

Tip

Batch Application Plugin と同様に、プロジェクトに固有のリポジトリを追加する場合、ビルドスクリプトのプラグイン定義 ( apply plugin: 'xxx' ) 位置の前にリポジトリ定義を追加すると、プラグインが標準で設定するリポジトリよりも優先して使用されます。

規約プロパティ

Framework Organizer Plugin の規約プロパティはビルドスクリプトから 参照名 asakusafwOrganizer でアクセスできます 17 。この規約オブジェクトは以下のプロパティを持ちます。

Framework Organizer Plugin - 規約プロパティ

プロパティ名

型

デフォルト値

説明

assembleDir

String

${project.buildDir}/asakusafw-assembly

デプロイメント構成の構築時に利用するワーキングディレクトリのプレフィックス

17

これらのプロパティは規約オブジェクト com.asakusafw.gradle.plugins.AsakusafwOrganizerPluginConvention [https://docs.asakusafw.com/0.10.3/release/gradle-plugins/com/asakusafw/gradle/plugins/AsakusafwOrganizerPluginConvention.html] が提供します。

バッチアプリケーションプロパティ

バッチアプリケーションの構成に関する規約プロパティは、 asakusafwOrganizer ブロック内の参照名 batchapps でアクセスできます 18 。この規約オブジェクトは以下のプロパティを持ちます。

Framework Organizer Plugin - バッチアプリケーションプロパティ ( batchapps ブロック )

プロパティ名

型

デフォルト値

説明

enabled

boolean

true

この値をtrueにするとデプロイメントアーカイブにプロジェクトのバッチアプリケーションを含める

18

これらのプロパティは規約オブジェクト com.asakusafw.gradle.plugins.AsakusafwOrganizerPluginConvention.BatchappsConfiguration [https://docs.asakusafw.com/0.10.3/release/gradle-plugins/com/asakusafw/gradle/plugins/AsakusafwOrganizerPluginConvention.BatchappsConfiguration.html] が提供します。

Hadoopプロパティ

Hadoopの構成に関する規約プロパティは、 asakusafwOrganizer ブロック内の参照名 hadoop でアクセスできます 19 。この規約オブジェクトは以下のプロパティを持ちます。

Framework Organizer Plugin - Hadoopプロパティ ( hadoop ブロック )

プロパティ名

型

デフォルト値

説明

embed

boolean

false

この値をtrueにするとデプロイメントアーカイブにHadoopライブラリーを含める

19

これらのプロパティは規約オブジェクト com.asakusafw.gradle.plugins.AsakusafwOrganizerPluginConvention.HadoopConfiguration [https://docs.asakusafw.com/0.10.3/release/gradle-plugins/com/asakusafw/gradle/plugins/AsakusafwOrganizerPluginConvention.HadoopConfiguration.html] が提供します。

See also

Hadoopプロパティの利用方法については、 Asakusa on M3BPユーザーガイド - Hadoopとの連携 を参照してください。

MapReduceプロパティ

MapReduce DSLコンパイラが生成するバッチアプリケーションの構成に関する規約プロパティは、 asakusafwOrganizer ブロック内の参照名 mapreduce でアクセスできます。

この規約オブジェクトについては、Asakusa on MapReduceの以下のドキュメントを参照してください。

Asakusa on MapReduce リファレンス - Framework Organizer Plugin ( asakusafwOrganizer ) への拡張

Sparkプロパティ

Spark DSLコンパイラが生成するバッチアプリケーションの構成に関する規約プロパティは、 asakusafwOrganizer ブロック内の参照名 spark でアクセスできます。

この規約オブジェクトについては、Asakusa on Sparkの以下のドキュメントを参照してください。

Asakusa on Spark リファレンス - Framework Organizer Plugin ( asakusafwOrganizer ) への拡張

M3BPプロパティ

M³BP DSLコンパイラが生成するバッチアプリケーションの構成に関する規約プロパティは、 asakusafwOrganizer ブロック内の参照名 m3bp でアクセスできます。

この規約オブジェクトについては、 Asakusa on M³BP の以下のドキュメントを参照してください。

Asakusa on M3BPリファレンス - Framework Organizer Plugin ( asakusafwOrganizer ) への拡張

Direct I/Oプロパティ

Direct I/Oの構成に関する規約プロパティは、 asakusafwOrganizer ブロック内の参照名 directio でアクセスできます 20 。この規約オブジェクトは以下のプロパティを持ちます。

Framework Organizer Plugin - Direct I/Oプロパティ ( directio ブロック )

プロパティ名

型

デフォルト値

説明

enabled

boolean

true

この値をtrueにするとDirect I/O用の構成を行う

20

これらのプロパティは規約オブジェクト com.asakusafw.gradle.plugins.AsakusafwOrganizerPluginConvention.DirectIoConfiguration [https://docs.asakusafw.com/0.10.3/release/gradle-plugins/com/asakusafw/gradle/plugins/AsakusafwOrganizerPluginConvention.DirectIoConfiguration.html] が提供します。

Hiveプロパティ

Direct I/O Hiveの構成に関する規約プロパティは、 asakusafwOrganizer ブロック内の参照名 hive でアクセスできます 21 。この規約オブジェクトは以下のプロパティを持ちます。

Framework Organizer Plugin - Hiveプロパティ ( hive ブロック )

プロパティ名

型

デフォルト値

説明

enabled

boolean

false

この値をtrueにすると Direct I/O Hive連携モジュール用の構成を行う

libraries

java.util.List

org.apache.hive:hive-exec:1.2.2

Directi I/O Hiveが実行時に使用するHiveライブラリ 22

21

これらのプロパティは規約オブジェクト com.asakusafw.gradle.plugins.AsakusafwOrganizerPluginConvention.HiveConfiguration [https://docs.asakusafw.com/0.10.3/release/gradle-plugins/com/asakusafw/gradle/plugins/AsakusafwOrganizerPluginConvention.HiveConfiguration.html] が提供します。

22

設定方法の例や詳細については、 Direct I/O Hive を参照してください。

テストドライバープロパティ

テストモジュール用の構成に関する規約プロパティは、 asakusafwOrganizer ブロック内の参照名 testing でアクセスできます 23 。この規約オブジェクトは以下のプロパティを持ちます。

Framework Organizer Plugin - テストモジュールプロパティ ( testing ブロック )

プロパティ名

型

デフォルト値

説明

enabled

boolean

false

この値をtrueにするとテストモジュール用の構成を行う

23

これらのプロパティは規約オブジェクト com.asakusafw.gradle.plugins.AsakusafwOrganizerPluginConvention.TestingConfiguration [https://docs.asakusafw.com/0.10.3/release/gradle-plugins/com/asakusafw/gradle/plugins/AsakusafwOrganizerPluginConvention.TestingConfiguration.html] が提供します。

WindGateプロパティ

WindGateの構成に関する規約プロパティは、 asakusafwOrganizer ブロック内の参照名 windgate でアクセスできます 24 。この規約オブジェクトは以下のプロパティを持ちます。

Framework Organizer Plugin - WindGateプロパティ ( windgate ブロック )

プロパティ名

型

デフォルト値

説明

enabled

boolean

true

この値をtrueにするとWindGate用の構成を行う

retryableEnabled

boolean

false

この値をtrueにするとWindGateプラグイン asakusa-windgate-retryable を追加する 25

sshEnabled

boolean

true

この値をtrueにするとHadoopブリッジ ( windgate-ssh ) を追加する 26

24

これらのプロパティは規約オブジェクト com.asakusafw.gradle.plugins.AsakusafwOrganizerPluginConvention.WindGateConfiguration [https://docs.asakusafw.com/0.10.3/release/gradle-plugins/com/asakusafw/gradle/plugins/AsakusafwOrganizerPluginConvention.WindGateConfiguration.html] が提供します。

25

詳しくは WindGateユーザーガイド - 再試行可能なデータ転送プロセス を参照してください。

26

詳しくは WindGateユーザーガイド - SSH経由でリモートのHadoopを利用する を参照してください。

YAESSプロパティ

YAESSの構成に関する規約プロパティは、 asakusafwOrganizer ブロック内の参照名 yaess でアクセスできます 27 。この規約オブジェクトは以下のプロパティを持ちます。

Framework Organizer Plugin - YAESSプロパティ ( yaess ブロック )

プロパティ名

型

デフォルト値

説明

enabled

boolean

true

この値をtrueにするとYAESS用の構成を行う

hadoopEnabled

boolean

true

この値をtrueにするとHadoopブリッジ ( yaess-hadoop ) を追加する 28

jobqueueEnabled

boolean

false

この値をtrueにするとYAESSプラグイン asakusa-yaess-jobqueue を追加する 29

toolsEnabled

boolean

true

この値をtrueにするとYAESS拡張ツールを追加する

iterativeEnabled

boolean

true

この値をtrueにするとYAESSのIterative Extensions向け拡張モジュールを追加する 30

27

これらのプロパティは規約オブジェクト com.asakusafw.gradle.plugins.AsakusafwOrganizerPluginConvention.YaessConfiguration [https://docs.asakusafw.com/0.10.3/release/gradle-plugins/com/asakusafw/gradle/plugins/AsakusafwOrganizerPluginConvention.YaessConfiguration.html] が提供します。

28

詳しくは YAESSユーザーガイド - SSHを経由してHadoopジョブを実行する を参照してください。

29

詳しくは YAESS JobQueue - JobQueueクライアントプラグインの利用方法 を参照してください。

30

Iterative ExtensionsについてはAsakusa on Sparkのドキュメント Asakusa on Spark Iterative Extensions を参照してください。

フレームワーク拡張プロパティ

Asakusa Frameworkの拡張構成に関する規約プロパティは、 asakusafwOrganizer ブロック内の参照名 extension でアクセスできます 31 。この規約オブジェクトは以下のプロパティを持ちます。

Framework Organizer Plugin - フレームワーク拡張プロパティ ( extension ブロック )

プロパティ名

型

デフォルト値

説明

libraries

java.util.List

[]

$ASAKUSA_HOME/ext/lib 配下に配置するライブラリ 32

31

これらのプロパティは規約オブジェクト com.asakusafw.gradle.plugins.AsakusafwOrganizerPluginConvention.ExtensionConfiguration [https://docs.asakusafw.com/0.10.3/release/gradle-plugins/com/asakusafw/gradle/plugins/AsakusafwOrganizerPluginConvention.ExtensionConfiguration.html] が提供します。

32

明示的に指定されたライブラリのみを配置し、明示的でない依存ライブラリ等は自動的に配置しません。

デプロイメントアーカイブの編集

デプロイメントアーカイブの構成方法として、コンポーネントの規約プロパティによってデプロイ構成を編集する機能の他に、デプロイメントアーカイブに任意のファイルを追加する機能を利用できます。

この機能は、 asakusafwOrganizer ブロック内の参照名 assembly でアクセスできます 33 。

以下は、 assembly の利用例です 34 。

build.gradle

asakusafwOrganizer {
    profiles.prod {
        assembly.into('.') {
            put 'src/dist/prod'
            replace 'asakusa-resources.xml', inputCombineMax: '24'
        }
    }
}

assembly.into は引数に指定したパス上に、ブロック配下の定義で対象とするファイルを追加します。

コンポーネントの規約プロパティによる構成で追加されるファイルと同名のファイルが含まれる場合は、ここで追加するファイルで上書きされるため、特定環境向けに構成した設定ファイルなどを含めることができます。

assembly.into ブロック内では以下のような指定が可能です 35 。

put

デプロイメントアーカイブ追加するディレクトリやファイルのパスを指定します。相対パスで指定した場合はプロジェクトディレクトリが起点となります。

replace

put の指定で追加の対象となるファイルに対して置換を行います。第1引数は置換の対象となるファイル名を指定します。ここで指定したパスは後方一致で評価されます。置換の対象となるファイル内の @key@ のように @ 文字で囲まれた文字列が置換対象となります。

後の引数に、置換対象文字列をMap形式 ( key:value )で指定します。

33

これらの機能は com.asakusafw.gradle.assembly.AsakusafwAssembly [https://docs.asakusafw.com/0.10.3/release/gradle-plugins/com/asakusafw/gradle/assembly/AsakusafwAssembly.html] が提供します。

34

assembly の利用例は、 Asakusa Framework デプロイメントガイド も参照してください。

35

これらの機能は com.asakusafw.gradle.assembly.AssemblyHandler [https://docs.asakusafw.com/0.10.3/release/gradle-plugins/com/asakusafw/gradle/assembly/AssemblyHandler.html] が提供します。

開発環境マイグレーションガイド

この文書では、Asakusa Framework のバージョンアップに伴う、開発環境のマイグレーション手順について解説します。

バージョン共通のマイグレーション手順

ここでは、各バージョン共通のマイグレーション手順について説明します。

Attention

ここで説明する手順に加えて、マイグレーション先のバージョンや現在利用している環境によっては、後述する バージョン固有のマイグレーション手順 が必要となる場合があるので必ずその内容も確認してください。

Gradleプロジェクトのマイグレーション

Gradleベースのアプリケーションプロジェクトについては、以下のドキュメントを参照してマイグレーションを実施してください。

Asakusa Gradle Plugin ユーザーガイド - Gradleプロジェクトのマイグレーション

Mavenプロジェクトのマイグレーション

Mavenベースのアプリケーションプロジェクトについては、以下のドキュメンを参照してGradleプロジェクトへのマイグレーションを実施してください。

Asakusa Gradle Plugin ユーザーガイド - Mavenプロジェクトのマイグレーション

バージョン固有のマイグレーション手順

バージョン 0.9.0 へのマイグレーション

Java (JDK)

Java7、およびJDK 7は非対応になりました。

Java7、およびJDK 7を利用している場合、Java8 (JDK 8)に移行する必要があります。

開発環境のJavaに関する設定については、以下のドキュメントを参照してください。

開発環境のJava

Gradle

Asakusa Gradle Pluginにいくつか仕様変更が行われ、一部のビルドスクリプトの設定方法が変更されています。

具体的なアプリケーションプロジェクトのマイグレーション手順については、以下のドキュメンを参照してください。

Asakusa Gradle Plugin マイグレーションガイド - Gradleプロジェクトのマイグレーション

また、Asakusa Gradle Pluginの動作に関する変更内容や、Asakusa Framework バージョン 0.8系 からのビルドスクリプトの移行方法については、以下のドキュメントを参照してください。

Asakusa Gradle Plugin バージョン 0.9系 の変更点

Asakusa Gradle Plugin マイグレーションガイド

ここでは、Asakusa Gradle Plugin で構築した開発環境のバージョンアップ手順や、 従来のAsakusa Frameworkが提供するMavenベースのビルドシステムからAsakusa Gradle Pluginを使ったビルドシステムに移行するための手順を説明します。

Asakusa Frameworkの各バージョン固有のマイグレーション情報については 開発環境マイグレーションガイド に説明があるので、こちらも必ず確認してください。

Gradleプロジェクトのマイグレーション

ここではAsakusa Gradle Pluginを利用したアプリケーションプロジェクトをマイグレーションする手順例を説明します。

Note

以降ではコマンドライン上での手順を説明しますが、Shafuを利用している場合も手順は同様です。利用するメニューなどについては、 Shafuのドキュメント [https://docs.asakusafw.com/jinrikisha/ja/html/shafu.html] を参照してください。

マイグレーション前のビルドの確認

Hint

この手順は必須ではありませんが、マイグレーション作業時に問題が発生した場合に備えて実施しておくことを推奨します。

マイグレーション以前の状態でプロジェクトのフルビルドを行い、ビルドが成功することを確認します。

./gradlew clean build

また、ビルドが成功した状態のプロジェクトをバックアップするなど、マイグレーション作業で問題が発生した場合にすぐに元の状態に戻れるようにしておきます。

Asakusa Gradle Pluginのバージョン変更

ビルドスクリプト内の buildscript ブロック内に定義しているAsakusa Gradle Pluginのバージョンの値を、アップデートするAsakusa Gradle Pluginのバージョンに変更します。

build.gradle

buildscript {
    repositories {
        maven { url 'http://asakusafw.s3.amazonaws.com/maven/releases' }
    }
    dependencies {
        classpath group: 'com.asakusafw.gradle', name: 'asakusa-distribution', version: '0.10.3'
    }
}

Attention

バージョン 0.8系以前のバージョンからマイグレーションする場合、利用するプラグインをディストリビューションプラグインに変更してください。

詳しくは、 Asakusa Gradle Plugin バージョン 0.9系 の変更点 を参照してください。

バージョン固有のビルドスクリプト設定の変更

Asakusa Frameworkの各バージョンで、ビルドスクリプトに関するバージョン固有のマイグレーション手順が示されている場合、ここでビルドスクリプトの内容を編集します。

バージョン固有のマイグレーション内容ついては、以下のドキュメントを参照してください。

開発環境マイグレーションガイド

バージョン 0.6系, 0.7系のGradleプロジェクトからバージョン 0.8系へのマイグレーション時には、必ず以下のドキュメントも参照してください。

Asakusa Gradle Plugin バージョン 0.8系 の変更点

バージョン 0.8系のGradleプロジェクトからバージョン 0.9系へのマイグレーション時には、必ず以下のドキュメントも参照してください。

Asakusa Gradle Plugin バージョン 0.9系 の変更点

バージョン 0.9系のGradleプロジェクトからバージョン 0.10系へのマイグレーション時には、必ず以下のドキュメントも参照してください。

Asakusa Gradle Plugin バージョン 0.10系 の変更点

Gradleラッパーのアップデート

アプリケーションプロジェクトで利用するGradleラッパーをAsakusa Gradle Pluginが推奨するバージョンにアップデートします。

プロジェクトディレクトリに移動し、 asakusaUpgrade タスクを実行します。

./gradlew asakusaUpgrade

asakusaUpgrade タスクを実行後、 help タスクを実行するとGradleラッパーのバージョンを確認できます。

./gradlew help

:help

Welcome to Gradle 4.7.
...

Attention

Shafuを利用している場合、ShafuはプロジェクトのGradleラッパーを使用せず、Shafu側で設定されているGradleを使用します。 Shafuが利用するGradleのバージョンをアップデートするにはShafu側の設定を変更する必要があります。

Shafuの設定については Shafuのドキュメント [https://docs.asakusafw.com/jinrikisha/ja/html/shafu.html] を参照してください。

Asakusa Frameworkの再インストール

開発環境のAsakusa Frameworkを再インストールします。

./gradlew installAsakusafw

マイグレーションしたビルド設定の確認

マイグレーション後の状態でプロジェクトのフルビルドを行い、ビルドが成功することを確認します。

./gradlew clean build

Eclipse定義ファイルの更新

Eclipseを利用している場合は、Eclipse用定義ファイルを更新します。

./gradlew cleanEclipse eclipse

Mavenプロジェクトのマイグレーション

ここでは、 Mavenアーキタイプ利用ガイド や Asakusa Framework バージョン 0.5.3 以前の Asakusa Framework スタートガイド 及び Jinrikisha (人力車) - Asakusa Framework Starter Package - [https://docs.asakusafw.com/jinrikisha/ja/html/index.html] で記載されている手順に従って構築した開発環境やMavenベースのアプリケーションプロジェクト(以下「Mavenプロジェクト」と表記)をAsakusa Gradle Pluginを使った環境にマイグレーションする手順を説明します。

Attention

プロジェクトのソースディレクトリに含まれるアプリケーションのソースコード(Asakusa DSL, DMDL, テストコードなど)についてのマイグレーション作業は不要で、そのまま利用することが出来ます。

マイグレーション前のビルドの確認

Hint

この手順は必須ではありませんが、マイグレーション作業時に問題が発生した場合に備えて実施しておくことを推奨します。

マイグレーション以前の状態でプロジェクトのフルビルドを行い、ビルドが成功することを確認します。

mvn clean package

また、ビルドが成功した状態のプロジェクトをバックアップするなど、マイグレーション作業で問題が発生した場合にすぐに元の状態に戻れるようにしておきます。

プロジェクトテンプレートの適用

Asakusa Gradle Pluginのプロジェクトテンプレートに含まれるファイル一式をMavenプロジェクトに適用します。

以下は、ダウンロードしたプロジェクトテンプレートを $HOME/workspace/migrate-app に適用する例です。

cd ~/Downloads
tar xf asakusa-*-template-*.tar.gz
cd asakusa-*-template
cp -a build.gradle gradlew gradlew.bat .buildtools ~/workspace/migrate-app

プロジェクト初期設定ファイルの適用

MavenプロジェクトとAsakusa Gradle Pluginのプロジェクトテンプレートの両方に含まれるプロジェクトの初期設定ファイルに対しては、以下のファイル内容を確認し、必要に応じてMavenプロジェクトに適用します。

MavenプロジェクトとAsakusa Gradle Pluginのプロジェクトテンプレートの両方に含まれるファイルの一覧を以下に示します。

ファイル

説明

src/test/resources/logback-test.xml

ビルド/テスト実行時に使用されるログ定義ファイル

Tip

Mavenプロジェクトで上記の設定ファイルをデフォルト設定のまま利用している場合は、Asakusa Gradle Pluginのプロジェクトテンプレートの内容で上書きすることを推奨します。

プロジェクト定義のマイグレーション

Mavenプロジェクトのプロジェクト定義( pom.xml )の内容をGradleのビルドスクリプト( build.gradle )に反映します。

pom.xml の代表的なカスタマイズ内容として、アプリケーションで利用するライブラリ追加による依存関係の設定があります。これは pom.xml 上では dependencies 配下に定義していました。

Gradle、およびAsakusa Gradle Pluginでは従来のMavenベースの依存関係の管理から一部機能が変更になっているため、 Asakusa Gradle Plugin ユーザーガイド - 依存ライブラリの管理 や Asakusa Gradle Plugin リファレンス などの内容を確認してアプリケーションに対して適切な設定を行ってください。

その他に確認すべき点は、標準プロジェクトプロパティの内容です。これに相当する内容はMavenアーキタイプからプロジェクトを作成する際に入力した内容が pom.xml のトップレベルの階層に定義されています。

以下、この箇所に該当する pom.xml の設定例です。

pom.xml

    <name>Example Application</name>
    <groupId>com.example</groupId>
    <artifactId>migrate-app</artifactId>
    <version>1.0-SNAPSHOT</version>

Gradleではこれらのプロパティについてビルドスクリプト上の定義は必須ではありませんが、必要に応じて pom.xml の設定を反映するとよいでしょう。

ビルド定義ファイルのマイグレーション

従来のMavenのビルド定義ファイル( build.properties )の内容をGradleのビルドスクリプト( build.gradle )に反映します。ビルド定義ファイルの内容は、移行後の build.gradle では Batch Application Plugin 上の規約プロパティとして定義します。

ここで必ず確認すべき項目は、Mavenアーキタイプでプロジェクトを作成した内容が反映される以下のプロパティです。

プロパティ

対応するbuild.gradle上の設定項目

説明

asakusa.modelgen.package

asakusafw.modelgen.modelgenSourcePackage

データモデルクラスに使用されるパッケージ名

その他の項目については、 build.properties をデフォルト値のまま利用している場合は移行作業は不要です。変更しているものがある場合は Asakusa Gradle Plugin ユーザーガイド - ビルド設定のカスタマイズ や Asakusa Gradle Plugin リファレンス 上の規約プロパティを確認し、設定を反映してください。

Asakusa Frameworkの再インストール

開発環境のAsakusa Frameworkを再インストールします。

./gradlew installAsakusafw

マイグレーションしたビルド設定の確認

マイグレーション後の状態でプロジェクトのフルビルドを行い、ビルドが成功することを確認します。

./gradlew clean build

Eclipse定義ファイルの更新

Eclipseを利用している場合は、Eclipse用定義ファイルを更新します。

./gradlew cleanEclipse eclipse

Mavenビルド用ファイルの削除

Mavenプロジェクトのビルドで利用していた以下のファイル、ディレクトリを削除します。

pom.xml

build.properties

target

Maven Framework Organizerのマイグレーション

従来の Maven Framework Organizer 1 で提供していた機能は、Asakusa Gradle Plugin によって提供されます。詳しくは Asakusa Gradle Plugin ユーザーガイド や Asakusa Gradle Plugin リファレンス の内容を確認してください。

1

Maven Framework Organizer利用ガイド

Asakusa Gradle Plugin バージョン 0.10系 の変更点

ここでは、Asakusa Gradle Plugin バージョン 0.9系 から 0.10系 の変更点について説明します。

Asakusa Gradle Pluginを利用したアプリケーションプロジェクトのマイグレーションについては、 Asakusa Gradle Plugin マイグレーションガイド も参照してください。

Asakusa on M³BP - Hadoopの連携

Asakusa on M³BPの Hadoopとの連携 についての標準の動作および設定は、Asakusa Framework バージョン 0.10.0 から以下のように変更されました。

過去バージョンでは、標準の設定では実行環境上にインストールしたHadoopと 連携しない よう設定されていたが、バージョン 0.10.0 からは標準の設定で実行環境上にインストールしたHadoopと 連携する よう変更された。

過去のバージョンでは、実行環境上にインストールしたHadoopと連携するために以下の設定を使用したが、バージョン 0.10.0 からはこれらの設定が廃止された（設定しても無効となる）。

asakusafwOrganizer.m3bp.useSystemHadoop

asakusafwOrganizer.profiles.<プロファイル名>.m3bp.useSystemHadoop

実行環境のHadoopと連携しない場合、Asakusa Frameworkの実行に必要な最低限のHadoopライブラリーをデプロイメントアーカイブに含めるために、以下の設定が追加された。

asakusafwOrganizer.hadoop.embed true

過去のバージョンから移行する場合、上記の変更に基づいてアプリケーションプロジェクトのビルドスクリプト build.gradle に対して以下の変更を行ってください｡

実行環境上にインストールしたHadoopと連携する場合

実行環境上にインストールしたHadoopと連携する場合、過去バージョンの build.gradle には以下の設定を追加しましたが、バージョン 0.10.0 以降はこの設定を削除してください。

asakusafwOrganizer.m3bp.useSystemHadoop

asakusafwOrganizer.profiles.<プロファイル名>.m3bp.useSystemHadoop

実行環境上にインストールしたHadoopと連携しない場合

実行環境上にインストールしたHadoopと連携しない場合、 build.gradle に以下の設定を追加してください。

asakusafwOrganizer.hadoop.embed true

以下は、 prod プロファイルのデプロイメントアーカイブに上記の設定を行う例です。

build.gradle

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.3'
    }
}

apply plugin: 'asakusafw-sdk'
apply plugin: 'asakusafw-organizer'
apply plugin: 'asakusafw-m3bp'
apply plugin: 'eclipse'

asakusafwOrganizer {
    profiles.prod {
        hadoop.embed true
    }
}

See also

Hadoopとの連携に関する設定については、Asakusa on M3BPユーザーガイド - Hadoopとの連携 も参照してください。

Asakusa Gradle Plugin バージョン 0.9系 の変更点

ここでは、Asakusa Gradle Plugin バージョン 0.8系 から 0.9系 の変更点について説明します。

Asakusa Gradle Pluginを利用したアプリケーションプロジェクトのマイグレーションについては、 Asakusa Gradle Plugin マイグレーションガイド も参照してください。

ディストリビューションプラグイン

Asakusa Gradle Pluginを利用する場合、これまではアプリケーションプロジェクトのビルドスクリプト build.gradle の buildscript ブロック内に利用するプラグインの定義を記述していました。

例えば Asakusa on Spark と Asakusa on M³BP を利用する場合、以下のように各コンポーネントが提供するそれぞれのGradle Pluginを記述していました。

build.gradle

buildscript {
    repositories {
        maven { url 'http://asakusafw.s3.amazonaws.com/maven/releases' }
    }
    dependencies {
        classpath group: 'com.asakusafw.spark', name: 'asakusa-spark-gradle', version: '0.3.1'
        classpath group: 'com.asakusafw.m3bp', name: 'asakusa-m3bp-gradle', version: '0.1.2'
    }
}

0.9系以降では、それぞれのGradle Pluginを記述する代わりにディストリビューションプラグイン com.asakusafw.gradle:asakusa-distribution の利用を推奨します。

以下は、ビルドスクリプトにディストリビューションプラグインを適用する例です。

build.gradle

buildscript {
    repositories {
        maven { url 'http://asakusafw.s3.amazonaws.com/maven/releases' }
    }
    dependencies {
        classpath group: 'com.asakusafw.gradle', name: 'asakusa-distribution', version: '0.9.0'
    }
}

ディストリビューションプラグインはAsakusa Frameworkのリリース時に動作検証を行った各サブプロジェクトの組み合わせによる Gradle Pluginのバージョンを自動的に適用し、これらを単一のバージョンで利用できるようにします。将来サブプロジェクトが追加された場合や構成が変更になった場合にも、マイグレーションの手順がシンプルになります。

例えば、ディストリビューションプラグインのバージョン 0.9.0 は以下のGradle Pluginを自動的に適用します。

com.asakusafw:asakusa-gradle-plugins:0.9.0

com.asakusafw.spark:asakusa-spark-gradle:0.4.0

com.asakusafw.m3bp:asakusa-m3bp-gradle:0.2.0

Attention

ディストリビューションプラグインを利用しない従来の方法でプラグインの定義を記述した場合、プラグインの定義に互換がないバージョンの組み合わせを設定できてしまうという問題があります。問題の一例として、それぞれのプラグインが利用するコアライブラリのバージョンが異なるため、実行時に互換がない実行ライブラリを使用してしまう、といった可能性があります。

アプリケーションSDKライブラリ

アプリケーションプロジェクトでバッチアプリケーションの開発に必要なライブラリを利用するために、これまではAsakusa Frameworkのライブラリをグループ化したSDKアーティファクト（ SDKアーティファクト利用ガイド ）を提供していました。

例えばアプリケーションのプロジェクトテンプレートの標準設定では、ビルドスクリプトの dependencies ブロック内にSDKアーティファクトの定義を記述していました。

build.gradle

dependencies {
    compile group: 'com.asakusafw.sdk', name: 'asakusa-sdk-core', version: asakusafw.asakusafwVersion
    compile group: 'com.asakusafw.sdk', name: 'asakusa-sdk-directio', version: asakusafw.asakusafwVersion
    compile group: 'com.asakusafw.sdk', name: 'asakusa-sdk-windgate', version: asakusafw.asakusafwVersion
    testRuntime group: 'com.asakusafw.sdk', name: 'asakusa-sdk-test-emulation', version: asakusafw.asakusafwVersion
}

0.9系以降では、上の例にある標準的なアプリケーションSDKライブラリはプロジェクトの依存ライブラリに自動的に追加されるようになりました。

このため、特別な理由がない限り、上記の例に示すSDKアーティファクトの定義はビルドスクリプトから削除することを推奨します。

アプリケーションSDKライブラリに関する設定を変更する場合、ビルドスクリプトの asakusafw ブロック配下の sdk で指定します。

試験的機能として提供している Direct I/O Hive 用のSDKアーティファクト com.asakusafw.sdk:asakusa-sdk-hive を利用している場合、標準の構成にはこのライブラリは含まれていないため、 dependencies ブロックから従来の定義を削除した上で、以下の定義を追加してください。

build.gradle

asakusafw {
    sdk.hive true
}

その他、アプリケーションプロジェクトで利用するSDKアーティファクトの定義を変更している場合は、 Asakusa Gradle Plugin リファレンス - Batch Application Plugin の「SDKプロパティ」の内容を確認して必要な設定を行ってください。

Attention

dependencies ブロック内に SDKアーティファクト利用ガイド に記載しているSDKアーティファクト以外の定義を追加している場合は、その定義はそのまま残しておく必要があります。

dependencies に定義を追加している主なケースには、演算子内で使用する任意のJavaライブラリを追加している場合や、 試験的機能 として提供しているコンパイラ拡張ライブラリを使用している場合などがあります。

Asakusa Frameworkバージョンの指定

バージョン 0.8.1 より、 ビルドスクリプト上の asakusafw.asakusafwVersion を利用したAsakusa Frameworkバージョンの指定は非推奨機能となりましたが、バージョン0.9系以降では、 この値をビルドスクリプト上で変更してもこの設定は無効になるよう変更されました。

また、これまではビルドスクリプトの asakusafwOrganizer ブロック dependencies ブロック内でAsakusa Frameworkのライブラリを指定する場合にも asakusafw.asakusafwVersion を利用していましたが、0.9系以降ではこれに代わり以下のプロパティを利用することを推奨します。

バージョンを保持するプロパティ

プロパティ名

説明

asakusafw.core.version

コアライブラリのバージョン。

asakusafw.mapreduce.version

Asakusa on MapReduceのバージョン。

asakusafw.spark.version

Asakusa on Sparkのバージョン。

asakusafw.m3bp.version

Asakusa on M³BP のバージョン。

プロパティの利用例は、 Direct I/O TSV の設定例などを参照してください。

デプロイメントアーカイブファイル名の変更

これまでは、アプリケーションプロジェクトで assemble タスクなどを実行して生成するデプロイメントアーカイブのファイル名は、標準で以下のファイル名を持っていました。

標準プロファイル: asakusafw-${asakusafwVersion}.tar.gz

追加プロファイル: asakusafw-${asakusafwVersion}-<profile-name>.tar.gz

0.9系以降では、標準で以下のファイル名に変更になりました。

標準プロファイル: asakusafw-${project.name}.tar.gz

追加プロファイル: asakusafw-${project.name}-<profile-name>.tar.gz

Asakusa Gradle Plugin バージョン 0.8系 の変更点

ここでは、Asakusa Gradle Plugin バージョン 0.6系, 0.7系 から 0.8系 の変更点について説明します。

Asakusa Gradle Pluginを利用したアプリケーションプロジェクトのマイグレーションについては、 Asakusa Gradle Plugin マイグレーションガイド も参照してください。

Gradleラッパーのアップデートに関する変更

アプリケーションプロジェクトに含まれるGradleラッパーをアップデートする手順が変更になりました。

過去のバージョンでは、 wrapper タスクを実行する手順を推奨していましたが、 0.8系以降では、Asakusa Gradle Pluginが提供する asakusaUpgrade タスクを利用してください。

asakusaUpgrade タスクは、Asakusa Gradle Pluginの該当バージョンで推奨されるGradleラッパーのバージョンをアプリケーションプロジェクトに導入します。

./gradlew asakusaUpgrade

また、この変更に伴いビルドスクリプトの wrapper タスクに関する定義は不要となりました。特別な理由がない限り、以下の例に示す wrapper タスクの定義はビルドスクリプトから削除することを推奨します。

build.gradle (以下の定義は不要)

task wrapper(type: Wrapper) {
    distributionUrl 'http://services.gradle.org/distributions/gradle-2.8-bin.zip'
    jarFile file('.buildtools/gradlew.jar')
}

ビルドスクリプトの設定に関する変更

プラグインの適用方法の変更

過去のバージョンでは、 ビルドスクリプトでAsakusa Gradle Pluginを適用する方法は、以下のように記述していました。

build.gradle

apply plugin: 'asakusafw'
apply plugin: 'asakusafw-organizer'

0.8系以降では、以下のように記述します。

build.gradle

apply plugin: 'asakusafw-sdk'
apply plugin: 'asakusafw-organizer'
apply plugin: 'asakusafw-mapreduce'

0.8系ではプラグイン構成が以下のように変更されています。

Asakusa Gradle Plugin - プラグイン構成

プラグインID

説明

asakusafw-sdk

バッチアプリケーション開発向けの基底となる機能を導入する

asakusafw-organizer

デプロイメントなど構成管理向けの基底となる機能を導入する

asakusafw-mapreduce

MapReduce向けのバッチアプリケーションを生成、実行するための機能を導入する

asakusafw-spark

Spark向けのバッチアプリケーションを生成、実行するための機能を導入する 1

asakusafw-legacy

ThunderGateなどのレガシーモジュールを利用するための機能を導入する

asakuafw

次のプラグイン機能を導入する: asakusafw-sdk , asakusafw-mapreduce, asakusafw-legacy 2

Warning

バージョン 0.9.0 より、 asakusafw-legacy は削除されました。

1

このプラグインは Asakusa on Spark Gradle Pluginが提供します。詳しくは Asakusa on Spark ユーザガイド を参照してください。

2

現時点では過去バージョンとの互換性のために必要なプラグイン機能を適用しています。なお、今後のバージョンで導入される機能が変更される可能性があります。

Asakusa Frameworkバージョンの指定

Attention

バージョン 0.8.1 より、 Asakusa Frameworkバージョンの指定 は非推奨機能に変更されました。本項の説明の通り、asakusafwVersion の定義をビルドスクリプトから削除することを強く推奨します。

0.8系以降ではHadoop1系が非対応となったことにより、Asakusa Framwork バージョン 0.7.0 から導入された「Hadoopバージョン」（<version>-hadoop1, <version>-hadoop2 のように、利用するHadoopのバージョンを持つバージョン体系）が廃止になりました。

0.8系以降は、Asakusa Frameworkのバージョンは単一のバージョン体系 ( 例えば 0.8.0 ) を使用します。

また、0.8系ではビルドスクリプト上の asakusafwVersion の指定はオプションになりました。 asakusafwVersion を指定しない場合、 Asakusa Gradle Pluginの該当バージョンが規定するAsakusa Frameworkバージョンを導入します。また、 Asakusa on Spark Gradle Pluginを利用する場合も同様に、このプラグインの該当バージョンが規定するAsakusa Frameworkバージョンを導入します。

Attention

通常、Asakusa Gradle Pluginはプラグインのバージョンと同一のAsakusa Frameworkバージョンを適用しますが、ホットフィックスリリースが行われた場合などにより異なるバージョンを適用する可能性があります。アプリケーションプロジェクトで利用される各コンポーネントのバージョンを確認する方法は、後述の Asakusa Frameworkバージョンの確認 を参照してください。

なお、検証されていない組み合わせの各Gradle PluginとAsakusa Frameworkバージョンを利用することは非推奨です。

これらの理由により、特別な理由がない限り以下の例に示す asakusafwVersion の定義はビルドスクリプトから削除することを推奨します。

build.gradle (以下の定義は不要)

asakusafw {
    asakusafwVersion '0.7.6-hadoop1'
...
}

asakusafwOrganizer {
    profiles.prod {
        asakusafwVersion asakusafw.asakusafwVersion
        ....
    }
    ....
}

Hadoopライブラリの指定

過去のバージョンでは、 バッチアプリケーションの開発時に使用するHadoopライブラリはビルドスクリプトの dependencies ブロックに設定する必要がありました。

0.8系以降では、Asakusa FrameworkのSDKアーティファクト asakusa-sdk-core 3 を経由して、Asakusa Frameworkの該当バージョンが規定するHadoopライブラリを導入します。

Attention

アプリケーションプロジェクトで利用されるHadoopライブラリのバージョンを確認する方法は、後述の Asakusa Frameworkバージョンの確認 を参照してください。

なお、ビルドスクリプトの設定でHadoopライブラリのバージョンを変更することは可能ですが、検証されていないHadoopライブラリのバージョンを利用することは非推奨です。

このため、特別な理由がない限り以下の例に示す dependencies ブロックのHadoopライブラリに関する定義はビルドスクリプトから削除することを推奨します。

build.gradle (以下の定義は不要)

dependencies {
    ...
    provided (group: 'org.apache.hadoop', name: 'hadoop-client', version: '1.2.1') {
        exclude module: 'junit'
        exclude module: 'mockito-all'
        exclude module: 'slf4j-log4j12'
    }

3

SDKアーティファクトについて詳しくは、 SDKアーティファクト利用ガイド を参照してください。

バッチアプリケーションのコンパイルに関する変更

コンパイルに使用するタスクの動作に関する変更

過去のバージョンでバッチアプリケーションのコンパイルを行うには、MapReduce向けのコンパイルは compileBatchapp タスクを利用し、 Spark向けのコンパイルは sparkCompileBatchapps タスクを利用していました。

また、 assemble タスクによってデプロイメントアーカイブを作成する際には常に compileBatchapp タスクが実行され、 Asakusa on Spark Gradle Pluginを適用している場合は常に sparkCompileBatchapps が実行されていました。

0.8系以降は、タスクの構成と動作が以下のように変更されています。

compileBatchapp タスク

ビルドスクリプトのプラグイン設定に従って利用可能なDSLコンパイラを全て実行します。

例えば、ビルドスクリプトにMapReduce向けのプラグイン asakusafw-mapreduce と Spark向けのプラグイン asakusafw-spark が適用されている場合、 compileBatchapp タスクを実行すると MapReduce向けのコンパイルとSpark向けのコンパイルをそれぞれ実行します。

Attention

0.8系から導入されたビルドスクリプトに対するプラグインの適用方法については先述の プラグインの適用方法の変更 を参照してください。

mapreduceCompileBatchapps タスク

MapReduceコンパイラによるバッチアプリケーションのコンパイルを実行します。

このタスクはビルドスクリプトにプラグイン asakusafw-mapreduce を適用することで利用可能になります。このプラグインを適用した状態で compileBatchapp タスクを実行すると、 mapreduceCompileBatchapps タスクが実行されます。

このタスクはバージョン0.8.0で新規で追加されました。

sparkeCompileBatchapps タスク

Sparkコンパイラによるバッチアプリケーションのコンパイルを実行します。

このタスクはビルドスクリプトにプラグイン asakusafw-spark を適用することで利用可能になります。このプラグインを適用した状態で compileBatchapp タスクを実行すると、 sparkCompileBatchapps タスクが実行されます。

assemble タスク

処理の過程で compileBatchapp タスクを実行するため、 compileBatchapp タスクの動作変更の影響を受けることに注意してください。

なお、バージョン 0.8.0から追加になった機能として、デプロイメント構成ごとに各DSLコンパイラの生成物を含めるかどうかの設定が可能になりました。

詳しくは、 Asakusa Gradle Plugin ユーザーガイド - デプロイメント構成に対するDSLコンパイラの無効化 を参照してください。

バッチアプリケーションのフィルタリングに関する変更

Asakusa Frameworkのバージョン 0.7.5 で compileBatchapp タスクに対してコンパイル対象をフィルタリングするための --update オプションが追加されましたが、バージョン 0.8.0 ではこのオプションは compileBatchapp タスクでは利用できなくなりました。代わりに、 mapreduceCompileBatchapps タスクで利用可能です。

sparkeCompileBatchapps ついては過去のバージョンと同様に、 --update オプションを利用することができます。

また、バージョン 0.8.0 ではMapReduceのコンパイルに関するフィルター設定をビルドスクリプト上に記述することができるようになりました。

詳しくは、 Asakusa Gradle Plugin ユーザーガイド - バッチコンパイル対象のフィルタリング を参照してください。

DSLコンパイラプロパティに関する変更

バージョン 0.8.0 より、 asakusafw ブロック内の参照名 compiler ブロックによるDSLコンパイラプロパティの指定は非推奨となりました。 MapReduceコンパイラに対する設定は、バージョン 0.8.0 から追加された mapreduce ブロックによるMapReduceプロパティの指定を使用してください。

なお、現時点では compiler ブロックによる設定も有効ですが、将来のバージョンでは使用できなくなる可能性があります。

MapReduceプロパティの指定や設定項目については、 Asakusa Gradle Plugin リファレンス を参照してください。

Asakusa Frameworkバージョンの確認

Asakusa Frameworkバージョンの指定 で説明した通り、0.8系ではAsakusa Gradle Plugin や Asakuas on Spark Gradle Plugin の定義によって自動的にAsakusa Frameworkバージョンが設定されることがあります。

そのため、0.8系からアプリケーションプロジェクトで利用されるAsakusa Frameworkバージョンやその他のコンポーネントバージョンを確認するための asakusaVersion タスクが追加されました。

./gradlew asakusaVersion

asakusaVersion タスクはビルドスクリプトの設定を解析し、以下のようにプロジェクトで利用するコンポーネントのバージョンを表示します。

:asakusaVersions
Asakusa Gradle Plug-ins: 0.8.0
Asakusa on Spark: 0.3.0
Asakusa SDK: 0.8.0
JVM: 1.7
Spark: 1.6.0
Hadoop: 2.7.2

過去の開発環境マイグレーションガイド

この文書では、Asakusa Framework のバージョンアップに伴う、開発環境のマイグレーション手順について解説します。

Gradleプロジェクトのマイグレーション手順

Asakusa Framework スタートガイド や Asakusa Gradle Plugin ユーザーガイド の手順に従って構築したアプリケーションプロジェクトについては、まず以下のドキュメントを参照してマイグレーションを実施してください。

Gradleプロジェクトのマイグレーション

上記ドキュメントの手順に加えて、バージョンによっては後述するバージョン固有のマイグレーション手順が必要となる場合があるので、必ず以下の内容を確認してください。

なお、複数バージョンをまたいだマイグレーションを行う場合は中間のバージョンの手順も確認し、パッチ適用手順などが提供されていた場合は、必ずそのパッチを順次適用するようにしてください。

バージョン 0.8.1 へのマイグレーション

Asakusa Frameworkバージョン指定の非推奨化

バージョン 0.8.1 より、プロジェクトのビルドスクリプト ( build.gradle ) でAsakusa Frameworkバージョンを指定することは非推奨となりました。

バージョン 0.7.6 より以前では、プロジェクトテンプレートに含まれるビルドスクリプトにAsakusa Frameworkバージョンの指定が含まれていました。このため特にバージョン 0.7.6 以前に作成したプロジェクトについては、Asakusa Gradle Plugin バージョン 0.8系 の変更点 - Asakusa Frameworkバージョンの指定の説明を確認の上、ビルドスクリプトからAsakusa Frameworkバージョンの指定を削除するよう変更してください。

なお本バージョンより、ビルドスクリプトにAsakusa Frameworkバージョンの指定が含まれている場合にはビルド時に警告が表示されるようになりました。

Direct I/O lineの利用方法

Direct I/O line が試験的機能から正式機能に変更になったことに伴い、 Direct I/O lineは SDKアーティファクト asakusa-sdk-directio に含まれるようになりました。プロジェクトテンプレートから作成したプロジェクトでは、このライブラリは標準で利用可能になっています。

バージョン 0.8.0 以前では、このライブラリは com.asakusafw.sandbox:asakusa-directio-dmdl-ext に含まれていました。このため、Direct I/O lineを利用するのみの目的でこのライブラリをビルドスクリプトに追加している場合、この定義は削除することができます。

バージョン 0.8.0 へのマイグレーション

Warning

バージョン 0.8.0 は以前のバージョンからいくつかの重要な変更が行われました。マイグレーションを検討する際には必ず以下の内容を確認してください。

Java (JDK)

Java6、およびJDK 6は非対応になりました。

Java6、およびJDK 6を利用している場合、Java 7(JDK 7)、またはJava8 (JDK 8)に移行する必要があります。

開発環境のJavaに関する設定については、以下のドキュメントを参照してください。

開発環境のJava

Hadoop

Hadoop1系は非対応となりました。

開発環境にHadoop1系をインストールしている場合、Hadoop2系をインストールしてAsakusa FrameworkからはHadoop2系を利用するよう設定してください。

開発環境にHadoop2系をインストールする方法については、以下のドキュメントを参照してください。

開発環境にHadoopを導入する

Gradle

Gradleのバージョン1系は非対応になりました。

また、Asakusa Gradle Pluginにいくつか仕様変更が行われ、一部のタスクの動作やビルドスクリプトの設定方法が変更されています。

具体的なアプリケーションプロジェクトのマイグレーション手順については、以下のドキュメンを参照してください。

Asakusa Gradle Plugin マイグレーションガイド - Gradleプロジェクトのマイグレーション

また、Asakusa Gradle Pluginの動作に関する変更内容や、Asakusa Framework バージョン 0.6系, 0.7系 からのビルドスクリプトの移行方法については、以下のドキュメントを参照してください。

Asakusa Gradle Plugin バージョン 0.8系 の変更点

Attention

Asakusa Gradle Plugin バージョン 0.8系 の変更点 には Asakusa Frameworkのバージョン体系の変更などの重要な内容が説明されているため、マイグレーション時には必ずこのドキュメントを確認してください。

Maven

Mavenの利用は非対応になりました。

Mavenを利用しているアプリケーションプロジェクトは、Gradleを利用するよう移行する必要があります。

Mavenベースのアプリケーションプロジェクトについては、以下のドキュメンを参照してGradleプロジェクトへのマイグレーションを実施してください。

Asakusa Gradle Plugin ユーザーガイド - Mavenプロジェクトのマイグレーション

バージョン 0.7.1 〜 0.7.6 へのマイグレーション

バージョン 0.7.1 から 0.7.6 におけるバージョン固有のマイグレーション手順はありません。各バージョン共通のマイグレーション手順のみを実施してください。

バージョン 0.7.0 へのマイグレーション

Warning

バージョン 0.7.0 は以前のバージョンからいくつかの重要な変更が行われました。マイグレーションを検討する際には必ず以下の内容を確認してください。

Asakusa Frameworkのバージョン体系の変更

バージョン 0.7.0 から Hadoop2系への対応が正式対応となりました。正式にサポートするHadoopのバージョンラインが複数になったことに伴い、Asakusa Frameworkのバージョン体系が以下のようになりました。

Hadoop1系向けAsakusa Framework

Asakusa Framework バージョン 0.x.x-hadoop1 というバージョン名でリリース

Hadoop2系向けAsakusa Framework

Asakusa Framework バージョン 0.x.x-hadoop2 というバージョン名でリリース

バージョン 0.6.x 以前ではHadoop1系向けAsakusa Frameworkは バージョン 0.x.x のようなバージョン体系でリリースされていましたが、バージョン 0.7.0 以降ではHadoop1系向けAsakusa Frameworkは バージョン 0.x.x-hadoop1 のように バージョン番号に ‘-hadoop1’ という接尾辞を指定 するように変更されています。

0.6.x 以前のバージョンからのマイグレーションを行う際には、アプリケーションプロジェクトのビルドスクリプト ( build.gradle ) などに含まれるAsakusa Frameworkバージョンに必ず新しいバージョン体系を指定してください。

なおHadoop2系向けのAsakusa Frameworkは以前のバージョンと同様に、バージョン番号に -hadoop2 という接尾辞を指定します。

例として、利用するAsakusa Framework を 0.6.2 から 0.7.0 に変更する場合の build.gradle のバージョン指定を示します。

build.gradle : Asakusa Framework 0.6.2 を利用するプロジェクトのバージョン指定

asakusafw {
    asakusafwVersion '0.6.2'

build.gradle : Asakusa Framework 0.7.0 を利用するプロジェクトのバージョン指定

asakusafw {
    asakusafwVersion '0.7.0-hadoop1'

Attention

build.gradle には先頭に buildscript ブロックでAsakusa Gradle Plugin のバージョンを指定しますが、このバージョンはAsakusa Frameworkのバージョン指定とは異なり、以下のようにバージョン番号に -hadoop1 や -hadoop2 といった接尾辞は付かないことに注意してください。

build.gradle

buildscript {
    repositories {
        maven { url 'http://asakusafw.s3.amazonaws.com/maven/releases' }
    }
    dependencies {
        classpath group: 'com.asakusafw', name: 'asakusa-gradle-plugins', version: '0.7.0'
    }
}

開発環境と運用環境で異なるHadoopバージョンを使用する

バージョン 0.7.0 では、開発環境で使用するHadoopはHadoop1系の利用を推奨しています。

また、Jinrikisha [https://docs.asakusafw.com/jinrikisha/ja/html/index.xml] や Asakusa Framework スタートガイド の手順に従ってセットアップされる開発環境はHadoop1系が利用されます。

Note

開発環境でHadoop1系の利用を推奨している主な理由は、現時点では開発環境の動作検証で使用しているHadoopプラットフォームにおいて、スタンドアロンモードの実行効率がHadoop1系のほうが良好であると判断しているためです。

バージョン 0.6.x 以前では 開発環境と運用環境で異なるHadoopバージョンを利用する場合に、開発環境を構成するアプリケーションプロジェクトとは別に、運用環境を構成する独立したプロジェクトの作成を推奨していました。

バージョン 0.7.0 からはそれぞれの環境の構成を「プロファイル」として記述し、アプリケーションプロジェクト内で複数のプロファイルを管理する方式を推奨しています。

プロファイルの利用方法(例えば開発環境でHadoop1系を利用し、運用環境でHadoop2系を利用するための設定)については、以下のドキュメントを参照してください。

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

また、この変更に伴いバージョン 0.6.x で提供していたAsakusa Gradle Pluginの一部機能が非推奨になりました。非推奨となったAsakusa Gradle Pluginについては、以下のドキュメントを参照してください。

Asakusa Gradle Plugin:非推奨機能

標準設定で使用するJavaバージョンの変更

バージョン 0.7.0 から Asakusa Gradle Pluginでアプリケーションプロジェクトに設定されるJavaバージョンが JDK6 から JDK7 に変更になりました。

Java 7に対応していないHadoopディストリビューション上でアプリケーションを実行する場合、プロジェクトの設定でJDK 6を利用するよう変更する必要があります。

プロジェクトで利用するJavaバージョンをJDK 6に変更する手順は、以下のドキュメントを参照してください。

開発環境のJava

プロジェクトテンプレートのGradleバージョンの変更

バージョン 0.7.0 から プロジェクトテンプレートに標準で設定されるGradleバージョンが 1.12 から 2.1 に変更になりました。

過去のバージョンで作成したアプリケーションプロジェクトのGradleのバージョンを変更する場合は、以下のドキュメントを参照してください。

Asakusa Gradle Plugin ユーザーガイド - Gradleラッパーのアップデート

Attention

バージョン 0.6.2 以前のAsakusa FrameworkはGradle 2.0以降に対応していません。プロジェクトのAsakusa Frameworkのバージョンをダウングレードする場合は、必ず利用するGradleのバージョンを合わせて変更してください

Mavenプロジェクトの非推奨化

バージョン 0.7.0 から Mavenプロジェクトは非推奨になりました。

本バージョンにおいては、 MavenプロジェクトからでもAsakusa Frameworkの多くの機能は従来通り利用できますが、本バージョンからMavenプロジェクト特有の機能の動作検証は行われなくなったため、Gradleプロジェクトへの移行を強く推奨します。

MavenプロジェクトからGradleプロジェクトへのマイグレーション手順については、 Asakusa Gradle Plugin ユーザーガイド - Mavenプロジェクトのマイグレーション を参照してください。

Attention

バージョン 0.7.0 のドキュメントから動作検証が行われていない一部のMavenプロジェクト向け機能に関する説明が削除されました。

0.6.2 へのマイグレーション

バージョン0.6.2におけるバージョン固有のマイグレーション手順はありません。各バージョン共通のマイグレーション手順のみを実施してください。

0.6.1 へのマイグレーション

バージョン0.6.1におけるバージョン固有のマイグレーション手順はありません。各バージョン共通のマイグレーション手順のみを実施してください。

0.6.0 へのマイグレーション

バージョン0.6.0ではプロジェクトテンプレートに含まれるファイルに対して細かな修正やディレクトリ構成の変更が行われたため、バージョン0.6.0で提供しているプロジェクトテンプレートの内容に置き換えることを推奨します。

プロジェクトテンプレートの置き換えについては、 Asakusa Gradle Plugin ユーザーガイド - マイグレーション前のビルドの確認 の項などを参照してください。

0.5.3 へのマイグレーション

バージョン 0.5.3 以前については、過去バージョンのドキュメントを参照してください。

開発環境のJava

この文書では、開発環境で利用するJava(JDK)環境やバージョンについて、また利用するJavaに応じたアプリケーションプロジェクトの設定について説明します。

See also

Asakusa Frameworkが動作検証を行なっているプラットフォーム環境の情報については、 対応プラットフォーム を参照してください。

開発環境で利用するJDK

Asakusa Framework バージョン 0.10.3 では主に Oracle JDK [http://www.oracle.com/technetwork/jp/java/javase/index.html] で動作検証を行なっています。

Attention

Jinrikisha [https://docs.asakusafw.com/jinrikisha/ja/html/index.xml] を使って開発環境を構築する場合、試用を目的として Open JDK [http://openjdk.java.net/] を使ったセットアップを行う機能を提供していますが、 Open JDK [http://openjdk.java.net/] では簡単な動作検証のみを行なっているため、試用目的以外の用途でAsakusa Frameworkを使用する場合は Oracle JDK [http://www.oracle.com/technetwork/jp/java/javase/index.html] を利用してください。

JDKのインストール

Oracle JDKの入手やインストール方法については、OracleのJavaのサイトなど 1 を参照してください。

1

https://docs.oracle.com/javase/jp/8/docs/technotes/guides/install/install_overview.html

開発ツールが利用するJDKの設定

GradleやEclipseなどの開発ツールが利用するためのJDKの設定を行います。

通常、これらは環境変数 $PATH や $JAVA_HOME に対して、インストールしたJDKのパスを設定します。詳しくは各ツールのドキュメントなどを参照してください。

アプリケーションプロジェクトの設定

Asakusa Frameworkのバージョン 0.10.3 では、アプリケーション開発環境のJavaバージョンの設定は、デフォルトでJDK 8(JDK 1.8)を利用する環境向けに設定されています。

Attention

Asakusa Framework バージョン 0.9.0 からJDK 7の利用は非対応となりました。

Attention

Asakusa Framework バージョン 0.9.0 からアプリケーション開発環境向けのデフォルト設定が JDK 7からJDK 8に変更になりました。過去バージョンからのマイグレーションに関する注意点などは、 開発環境マイグレーションガイド も参照してください。

Javaバージョンに関する設定

Asakusa Framework スタートガイド や Asakusa Gradle Plugin ユーザーガイド を利用して作成したアプリケーションプロジェクトは、Javaバージョンの設定に関して以下の設定を持ちます。

ソースコードのバージョン ( source )

javac(Javaコンパイラ)が受け付けるソースコードのバージョンを指定します。 Asakusa Frameworkのバージョン 0.10.3 ではデフォルトでこの値が 1.8 に設定されています。

ターゲットのクラスファイルバージョン ( target )

javacが生成するクラスファイルのバージョンを指定します。 Asakusa Frameworkのバージョン 0.10.3 ではデフォルトでこの値が 1.8 に設定されています。

EclipseのJRE用クラスパスコンテナ

Eclipseがプロジェクトに対して使用するJDKのバージョンを指定します。 Asakusa Frameworkのバージョン 0.10.3 ではこの値が JavaSE-1.8 に設定されています 2 。

2

Asakusa Gradle Plugin はソースコードのバージョンに対応するEclipseのJRE用クラスパスコンテナを設定します。

Javaバージョンの変更

アプリケーションプロジェクトのJavaバージョンに関する設定に変更する場合、 build.gradle に対して以下の設定を変更します。

build.gradleの設定

build.gradle に設定しているソースコードのバージョンとターゲットのクラスファイルバージョンを変更します。 asakusafw ブロックに javac ブロックを追加し、プロパティ sourceCompatibility と targetCompatibility の値に 利用するJavaバージョンを設定します。

以下は、Javaバージョンに 1.8 (JDK 8)を利用するための設定例です。

build.gradle

asakusafw {
    javac {
        sourceCompatibility '1.8'
        targetCompatibility '1.8'
    }
}

Eclipseプロジェクト情報の再構成

build.gradle の設定をEclipseのプロジェクト設定に反映するには、プロジェクト上で cleanEclipse タスクと eclipse タスクを実行します。

./gradlew cleanEclipse eclipse

IntelliJ IDEAの利用

この文書では、 IntelliJ IDEA [https://www.jetbrains.com/idea/] 上でAsakusa Frameworkのバッチアプリケーションを開発するための設定手順などを説明します。

Experimental

Asakusa Framework バージョン 0.10.3 では、 IntelliJ IDEAの利用は試験的機能として提供しています。将来のバージョンで本書の設定手順などが変更になる可能性があります。

本書では、 IntelliJ IDEA バージョン 2017.x を使った利用方法を説明します。バージョンによっては本書とは異なる画面やメニュー体系になっている場合がありますので、詳しくは IntelliJ IDEA のヘルプドキュメントなどを確認してください。

Gradle Wrapperの設定

IntelliJ IDEA上で Asakusa Gradle Plugin ユーザーガイド に記載のプロジェクトテンプレート ( プロジェクトテンプレートのダウンロード ) やこれをベースにした既存のアプリケーションプロジェクトをIntelliJ IDEAのGradleプロジェクトとしてインポートする場合、そのままの設定ではプロジェクトに含まれるGradle WrapperをIntelliJ IDEAが認識しません。

IntelliJ IDEAにプロジェクトに含まれるGradle Wrapperを認識させるには、以下のように build.gradle に Wrapper タスクの設定を追加します。

build.gradle

task wrapper(type: Wrapper) {
    gradleVersion = upgradeGradleWrapper.gradleVersion
    jarFile = upgradeGradleWrapper.jarFile
}

IntelliJ IDEAの起動

IntelliJ IDEAの起動時には、必ず環境変数 ASAKUSA_HOME が適用された状態で起動してください。

Project SDK (JDK) の登録

IntelliJ IDEAの Project SDK にJDK8が登録されていない場合(IntelliJ IDEAをはじめて利用するなどの場合)、まずProject SDKにJDK8を登録します。

以下はProject SDKの設定手順例です。

IntelliJ IDEA起動時に表示される Welcome Screen の画面下部から Configure ‣ Project Defaults ‣ Project Structure を選択します。

Default Project Structure 画面で New… ‣ JDK を選択します。

Select Home Directory for SDK 画面で JDK8のインストールディレクトリを選択します。

Default Project Structure 画面に戻ったら OK ボタンを押下します。

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

IntelliJ IDEAを起動したら、プロジェクトテンプレートや既存のアプリケーションプロジェクトをIntelliJ IDEAにインポートします。以下、インポートの手順例です。

IntelliJ IDEA起動時に表示される Welcome Screen から Import Project を選択します。

表示されるダイアログでインポートするプロジェクトのディレクトリを選択します。

Import Project ダイアログで Import project from external model - Gradle を選択し、Next ボタンを押下します。

続けて表示されるダイアログで以下のようにオプションを選択し、 Finish ボタンを押下します（以下に記載しない設定項目は任意です）。

Create separate module per source set : オフ 1

Use gradle wrapper task configuration : 選択 2 3

1

このオプションは IntelliJ IDEA 2016.1 以降のバージョンに存在します。現時点ではこのオプションをオンにするとAsakusa Gradle Pluginを適用したプロジェクトを正しくビルドすることができません。

2

このオプションを選択するには、 Gradle Wrapperの設定 の手順に従って build.gradle にWrapperタスクの設定を追加しておく必要があります。

3

Gradle Wrapperを使用せず、ローカルにインストールしたGradleを使用する場合は Use local gradle distribution を選択します。

コンパイラと注釈プロセッサの設定

インポートしたプロジェクト上でOperator DSLコンパイラを使用するために、IntelliJ IDEAのコンパイラと注釈プロセッサの設定を行います。

プロジェクトの設定画面を表示します 4 。

設定画面左のメニューから Build, Execution, Deployment ‣ Compiler を選択してコンパイラの設定画面を表示します。

コンパイラの設定画面で、 Build project automatically を オンにして、画面下部の Apply ボタンを押下します。

設定画面左のメニューから Build, Execution, Deployment ‣ Compiler ‣ Annotation Processors を選択して注釈プロセッサの設定画面を表示します。

注釈プロセッサの設定画面で以下のようにオプションを選択および入力し、 画面下部の OK ボタンを押下します。

Enable annotation processing : オン

Obtain processors from project classpath : 選択

Store generated sources relative to : Module content root を選択

Production sources directory : build/generated-sources/annotations

Test sources directory : build/generated-sources/generated_tests 5

4

設定画面の表示方法については、次のドキュメントなどを参照してください。 https://www.jetbrains.com/help/idea/accessing-settings.html

5

現時点でのAsakusa Frameworkでは使用しません。

Gradleタスクの実行

IntelliJ IDEA上でGradleタスクを実行するには、 Gradle Tool Window を使うと便利です。

View ‣ Tool Windows ‣ Gradle を選択して Gradle Tool Window を表示します。

Gradle Tool Window ではプロジェクトで実行可能なGradleタスクを選択して実行できます。

Tasks ‣ asakusa framework build にはAsakusa Gradle Pluginが追加したアプリケーション開発用のタスクが含まれます。

Tasks ‣ asakusa framework organizer にはAsakusa Gradle Pluginが追加したデプロイ構成用のタスクが含まれます。

Tasks ‣ build にはGradleが標準で提供するビルド用のタスクが含まれます。

Asakusa Gradle Plugin:非推奨機能

Deprecated

本書「Asakusa Gradle Plugin:非推奨機能」では、Asakusa Framework バージョン 0.10.3 で非推奨となっている Asakusa Gradle Plugin の機能をまとめています。本書に記載する機能は、いくつかの制約の元で動作するか、すでに使用できなくなっています。

基本的なプラグインの使用方法

Asakusa Frameworkのデプロイメントアーカイブ生成

Attention

バージョン 0.10.3 では、ここで紹介する assembleAsakusafw タスクの代わりに assemble タスクを利用してください。またデプロイメント構成の編集については、ここで紹介する方法の代わりに asakusafwOrganizer ブロックで定義してください。

Asakusa Frameworkを運用環境にデプロイするためのデプロイメントアーカイブを生成します。

運用環境向けの標準的な構成を持つデプロイメントアーカイブを生成するには、 assembleAsakusafw タスクを実行します。

./gradlew assembleAsakusafw

assembleAsakusafw タスクを実行すると、 build 配下に asakusafw-${asakusafwVersion}.tar.gz という名前でデプロイメントアーカイブが作成されます。このアーカイブには Direct I/O , WindGateを含むAsakusa Framework実行環境一式が含まれます。

このデプロイメントアーカイブは運用環境上の$ASAKUSA_HOME配下に展開してデプロイします。より詳しくは、 運用環境の整備 のデプロイメントガイドなどを参照してください。

バッチアプリケーションの同梱

attachBatchapps タスクは、 build/batchc 配下に存在するバッチアプリケーションをデプロイメントアーカイブに含めます。以下は、バッチアプリケーションの生成してこれを含むデプロイメントアーカイブを生成する例です。

./gradlew clean compileBatchapp attachBatchapps assembleAsakusafw

このようにタスクを実行すると、バッチコンパイルを実行後に build 配下に asakusafw-${asakusafwVersion}.tar.gz が生成され、このアーカイブの batchapps 配下には compileBatchapp タスクによって build/batchc 配下に生成されたバッチアプリケーションの実行ファイル一式が含まれます。

設定ファイル/アプリケーションライブラリの同梱

デプロイメントアーカイブに、特定の運用環境向けの設定ファイルやアプリケーション用の追加ライブラリを含めることもできます。

この機能を使用するには、まずプロジェクトディレクトリの src/dist 配下に特定環境を示す名前（以下この名前を「ディストリビューション名」と呼びます）を持つディレクトリを生成します。このディレクトリは英数小文字のみ使用できます。

ディストリビューション名のディレクトリ配下に、 $ASAKUSA_HOME のディレクトリ構造と同じ形式で追加したい設定ファイルやライブラリファイルを配置します。このディレクトリ構成がデプロイメントアーカイブにそのまま追加されます。

以下は、 src/dist 配下に myenv というディストリビューション名を持つのディレクトリを作成し、これに アプリケーション向けの追加ライブラリとYAESS 向けの設定ファイル を配置した例です。

src/dist
└── myenv
    ├── ext
    │   └── lib
    │       └── joda-time-2.2.jar
    └── yaess
        └── conf
            └── yaess.properties

src/dist 配下のディレクトリ構成をデプロイメントアーカイブに含めるには、 attachConf<ディストリビューション名> というタスクを実行します。タスク名の <ディストビューション名> 部分は src/dist 配下のディストリビューション名に対応し、これにマッチしたディレクトリ配下のファイル 1 をデプロイメントアーカイブに含めます。

タスク名の <ディストリビューション名> 部分は大文字/小文字の違いを無視します。例えば src/dist/myenv に対応するタスクは attachConfMyEnv にも対応します。

以下は、 src/dist/myenv 配下のファイルを含むデプロイメントアーカイブを生成する例です。

./gradlew attachConfMyEnv assembleAsakusafw

このようにタスクを実行すると、バッチコンパイルを実行後に build 配下に asakusafw-${asakusafwVersion}.tar.gz が生成され、このアーカイブには src/dist/myenv 以下のディレクトリ構造を含むファイル一式が含まれます。

1

. (ドット)から始まる名前を持つファイルやディレクトリは無視され、アーカイブに含まれません。

拡張モジュールの同梱

Asakusa Frameworkでは、標準のデプロイメントアーカイブに含まれない追加機能を拡張モジュール 2 として提供しています。

拡張モジュールは Asakusa Framworkの標準的なデプロイ構成にプラグインライブラリを追加することで利用することができます。Asakusa Gradle Plugin ではデプロイメントアーカイブの生成時に拡張モジュール取得用のタスクを合わせて実行することで、デプロイメントアーカイブに拡張モジュールを含めることができます。

以下は、拡張モジュール asakusa-windgate-retryable をデプロイメントアーカイブに含める例です。

./gradlew attachExtensionWindGateRetryable assembleAsakusafw

このようにタスクを実行すると、 build 配下に asakusafw-${asakusafwVersion}.tar.gz が生成され、このアーカイブには拡張モジュールが含まれた状態となります。今回の例では、アーカイブ内の windgate/plugin 配下に asakusa-windgate-retryable 用のjarファイルが追加されています。

2

拡張モジュールについて、詳しくは 拡張モジュールのデプロイ を参照してください。

組み合わせの例

これまで説明した内容を組み合わせて利用すると、特定環境向けのリリース用デプロイメントアーカイブをビルド時に作成することができます。

以下は、リリースビルドを想定したデプロイメントアーカイブ生成の実行例です。

./gradlew clean build attachBatchapps attachConfMyEnv attachExtensionWindGateRetryable assembleAsakusafw

このようにタスクを実行すると、テスト済のバッチアプリケーションと設定ファイル、追加ライブラリ、拡張モジュールを含むデプロイメントアーカイブを生成します。

その他のプラグイン機能

バッチテストランナーの実行

Attention

Asakusa Framework バージョン 0.10.0 より、 testRunBatchapp タスクは非推奨となりました。

testRunBatchapp タスクはインテグレーションテスト用のテストAPIであるバッチテストランナーをGradleタスクとして実行することができます。このタスクを利用するには、プロジェクトに対してAsakusa on MapReduce Plugin ( asakusafw-mapreduce ) を有効にする必要があります。

testRunBatchapp タスクは gradlew コマンド実行時に以下のコマンドライン引数を指定します。

--id batch-id

実行するバッチアプリケーションのバッチID

--arguments key1=value1 [,key2=value2]

バッチ引数を key=value 形式で指定

複数のバッチ引数がある場合はカンマ区切りで指定 ( key1=value1,key2=value2 )

testRunBatchapp タスクの実行例は以下の通りです。

./gradlew testRunBatchapp --id example.summarizeSales --arguments date=2011-04-01

See also

バッチテストランナーの詳細は テストドライバーユーザーガイド - バッチテストランナー を参照してください。

Asakusa Gradle Plugin リファレンス

Batch Application Plugin

タスク

Batch Application Plugin は、以下のタスクをプロジェクトに追加します。

Warning

バージョン 0.8.0 以降、ThunderGate関連の設定は利用できません。

Warning

バージョン 0.9.0 以降、以下のタスクは利用できません。

summarizeYaessJob

Batch Application Plugin - タスク

タスク名

依存先

型

説明

generateThunderGateDataModel

- 3

GenerateThunderGateDataModelTask 4

ThunderGate用のMySQLメタデータからDMDLスクリプトを生成する

summarizeYaessJob

asakusafw-sdk

AnalyzeYaessLogTask 5

YAESS Log Analyzerを実行する 6

3

ThunderGateの設定を有効にした場合、 compileDMDL タスクに generateThunderGateDataModel タスクが依存先として追加されます

4

com.asakusafw.gradle.tasks.GenerateThunderGateDataModelTask [https://docs.asakusafw.com/0.10.3/release/gradle-plugins/com/asakusafw/gradle/tasks/GenerateThunderGateDataModelTask.html]

5

com.asakusafw.gradle.tasks.AnalyzeYaessLogTask [https://docs.asakusafw.com/0.10.3/release/gradle-plugins/com/asakusafw/gradle/tasks/AnalyzeYaessLogTask.html]

6

YAESS Log Analyzerやその使い方については、 YAESSログの可視化 を参照してください。

規約プロパティ

Batch Application Pluginの規約プロパティはビルドスクリプトから 参照名 asakusafw でアクセスできます 7 。この規約オブジェクトは以下のプロパティを持ちます。

Batch Application Plugin - 規約プロパティ ( asakusafw ブロック )

プロパティ名

型

デフォルト値

説明

asakusafwVersion

String

プラグイン規定のバージョン 8

プロジェクトが使用するAsakusa Frameworkのバージョン

7

これらのプロパティは規約オブジェクト com.asakusafw.gradle.plugins.AsakusafwPluginConvention [https://docs.asakusafw.com/0.10.3/release/gradle-plugins/com/asakusafw/gradle/plugins/AsakusafwPluginConvention.html] が提供します。

8

Asakusa Gradle Pluginの該当バージョンが規定するAsakusa Frameworkバージョンを導入します。詳しくは後述の asakusafwVersion を参照してください。

asakusafwVersion

Attention

バージョン 0.9.0 以降、 Asakusa Frameworkバージョンの指定は無効になりました。

asakusafwVersion はアプリケーションプロジェクトで使用するAsakusa Frameworkのバージョンを表します。

Asakusa Gradle Pluginを利用する場合、このプラグインの該当バージョンが規定するAsakusa Frameworkバージョンを導入します。

通常、Asakusa Gradle Pluginはプラグインのバージョンと同一のAsakusa Frameworkバージョンを適用しますが、ホットフィックスリリースが行われた場合などにより異なるバージョンを適用する可能性があります。

アプリケーションプロジェクトで利用される各コンポーネントのバージョンを確認するには、 Asakusa Gradle Plugin が提供する asakusaVersion タスクを使用します。

なお、検証されていない組み合わせの各Gradle PluginとAsakusa Frameworkバージョンを利用することは非推奨です。特別な理由がない限り、 asakusafwVersion の定義はビルドスクリプトでは指定しない（標準の構成を使用する）ことを推奨します。

DSLコンパイラプロパティ

Attention

バージョン 0.8.0 以降、 compiler ブロックの指定は非推奨となりました。 MapReduceコンパイラに対する設定は、後述の MapReduceプロパティ を使用してください。

Attention

バージョン 0.10.3 時点では、 compiler ブロックではMapReduce DSLコンパイラに対する設定がおこなわれます。

DSLコンパイラ関する規約プロパティは、 asakusafw ブロック内の参照名 compiler でアクセスできます 9 。

この規約オブジェクトは以下のプロパティを持ちます。

Batch Application Plugin - DSLコンパイラプロパティ ( compiler ブロック )

プロパティ名

型

デフォルト値

説明

compiledSourcePackage

String

${asakusafw.basePackage}.batchapp

DSLコンパイラが生成する各クラスに使用されるパッケージ名

compiledSourceDirectory

String

${project.buildDir}/batchc

DSLコンパイラが生成する成果物の出力先

compilerOptions

String

XjavaVersion=${targetCompatibility} 10

DSLコンパイラオプション 11

compilerWorkDirectory

String

未指定

DSLコンパイラのワーキングディレクトリ

hadoopWorkDirectory

String

target/hadoopwork/${execution_id}

DSLコンパイラが生成するアプリケーション(Hadoopジョブ)が使用するHadoop上のワーキングディレクトリ

9

これらのプロパティは規約オブジェクト com.asakusafw.gradle.plugins.AsakusafwPluginConvention.CompilerConfiguration [https://docs.asakusafw.com/0.10.3/release/gradle-plugins/com/asakusafw/gradle/plugins/AsakusafwPluginConvention.CompilerConfiguration.html] が提供します。

10

Javaコンパイラプロパティの targetCompatibility の値が設定されます。

11

DSLコンパイラオプションについては、 Asakusa on MapReduce リファレンス - Asakusa DSL Compiler for MapReduce リファレンス を参照してください。

ThunderGateプロパティ

ThunderGateに関する規約プロパティは、 asakusafw ブロック内の参照名 thundergate でアクセスできます 12 。この規約オブジェクトは以下のプロパティを持ちます。

Batch Application Plugin - ThunderGateプロパティ ( thundergate ブロック )

プロパティ名

型

デフォルト値

説明

target

String

未指定

ThunderGateのターゲット。この値をセットすることでThunderGate用のビルド設定が有効になる 13

jdbcFile

String

未指定

generateThunderGateDataModel タスクの実行時に使用するJDBC接続設定ファイルのパス。この値をセットすることでThunderGate用のビルド設定が有効になる 14

ddlEncoding

String

未指定

MySQLメタデータ登録用DDLファイルのエンコーディング

ddlSourceDirectory

String

src/${project.sourceSets.main.name}/sql/modelgen

MySQLメタデータ登録用DDLファイルのソースディレクトリ

includes

String

未指定

モデルジェネレータ、およびテストデータテンプレート生成ツールが生成対象とするモデル名を正規表現の書式で指定

excludes

String

未指定

モデルジェネレータ、およびテストデータテンプレート生成ツールが生成対象外とするモデル名を正規表現の書式で指定

dmdlOutputDirectory

String

${project.buildDir}/thundergate/dmdl

MySQLメタデータから生成されるDMDLスクリプトの出力先

ddlOutputDirectory

String

${project.buildDir}/thundergate/sql

ThunderGate管理テーブル用DDLスクリプトの出力先

sidColumn

String

SID

ThunderGateが入出力を行う業務テーブルのシステムIDカラム名

timestampColumn

String

UPDT_DATETIME

ThunderGateが入出力を行う業務テーブルの更新日時カラム名

deleteColumn

String

DELETE_FLAG

ThunderGateが入出力を行う論理削除フラグカラム名

deleteValue

String

'1'

ThunderGateが入出力を行う業務テーブルの論理削除フラグが削除されたことを示す値

12

これらのプロパティは規約オブジェクト com.asakusafw.gradle.plugins.AsakusafwPluginConvention.ThunderGateConfiguration [https://docs.asakusafw.com/0.10.3/release/gradle-plugins/com/asakusafw/gradle/plugins/AsakusafwPluginConvention.ThunderGateConfiguration.html] が提供します。

13

この設定を利用する場合、タスク実行時にAsakusa Frameworkがインストール済みとなっている必要があります。または jdbcFile をプロパティを設定することで、インストールを行わない状態でタスクが実行できるようになります。

14

target プロパティを同時に有効にした場合、 jdbcFile プロパティが優先されます。

Framework Organizer Plugin

タスク

Framework Organizer Plugin は、以下のタスクを定義します。

Warning

バージョン 0.9.0 以降、以下のタスクは削除されました。

attachComponentDevelopment

Attention

バージョン 0.7.0 以降、 attach から始まる各タスクの使用は非推奨となりました。 attach から始まるタスクはFramework Organizer Pluginが内部で生成し利用します。

デプロイメントアーカイブ構築のカスタマイズ方法について、バージョン 0.7.0 以降では、 attach から始まる各タスクを組み合わせる方式から build.gradle 内の asakusafwOrganizer ブロックでデプロイメント構成を定義する方法を推奨するよう変更しています。

詳しくは、 Asakusa Framework デプロイメントガイド や Asakusa Gradle Plugin リファレンス を参照してください。

Warning

バージョン 0.7.0 以降では、以下のタスクは削除されました。

attachAssemble

attachAssembleDev

assembleCustomAsakusafw

assembleDevAsakusafw

複数のデプロイメントアーカイブ構成を管理する機能として、バージョン 0.7.0 以降ではプロファイル定義による構成機能を提供しています。

詳しくは、 Asakusa Framework デプロイメントガイド や Asakusa Gradle Plugin リファレンス を参照してください。

Framework Organizer Plugin - タスク

タスク名

依存先

型

説明

attachBatchapps

-

Task

デプロイメント構成にバッチアプリケーションを追加する 15

attachComponentCore

-

Task

デプロイメント構成にランタイムコアモジュールを追加する

attachComponentDirectIo

-

Task

デプロイメント構成にDirect I/Oを追加する

attachComponentYaess

-

Task

デプロイメント構成にYAESSを追加する

attachComponentWindGate

-

Task

デプロイメント構成にWindGateを追加する

attachComponentThunderGate

-

Task

デプロイメント構成にThunderGateを追加する

attachComponentDevelopment

-

Task

デプロイメント構成に開発ツールを追加する

attachComponentOperation

-

Task

デプロイメント構成に運用ツールを追加する

attachExtensionYaessJobQueue

-

Task

デプロイメント構成にYAESS JobQueue Pluginを追加する

attachExtensionWindGateRetryable

-

Task

デプロイメント構成にWindGate Retryable Pluginを追加する

attachConf< DistributionName >

-

Task

デプロイメント構成にディストリビューション名に対応するディレクトリを追加する 16

attachAssembleDev

attachBatchapps, attachComponentCore, attachComponentDirectIo, attachComponentYaess, attachComponentWindGate, attachComponentDevelopment, attachComponentOperation

Task

開発環境向けのデプロイメント構成を構築する

attachAssemble

attachComponentCore, attachComponentDirectIo, attachComponentYaess, attachComponentWindGate, attachComponentOperation

Task

運用環境向けのデプロイメント構成を構築する

assembleCustomAsakusafw

-

Task

任意のデプロイメント構成を持つデプロイメントアーカイブを生成する

assembleDevAsakusafw

attachAssembleDev

Task

開発環境向けのデプロイメント構成を持つデプロイメントアーカイブを生成する

15

attachBatchapps タスクを利用するには本プラグインをアプリケーションプロジェクト上で利用する必要があります。

16

attachConf<DistributionName> タスクを利用するには本プラグインをアプリケーションプロジェクト上で利用する必要があります。

規約プロパティ

Framework Organizer Plugin の規約プロパティはビルドスクリプトから 参照名 asakusafwOrganizer でアクセスできます 17 。この規約オブジェクトは以下のプロパティを持ちます。

Framework Organizer Plugin - 規約プロパティ

プロパティ名

型

デフォルト値

説明

asakusafwVersion

String

プラグイン規定のバージョン 18

プロジェクトが使用するAsakusa Frameworkのバージョン

17

これらのプロパティは規約オブジェクト com.asakusafw.gradle.plugins.AsakusafwOrganizerPluginConvention [https://docs.asakusafw.com/0.10.3/release/gradle-plugins/com/asakusafw/gradle/plugins/AsakusafwOrganizerPluginConvention.html] が提供します。

18

Asakusa Gradle Pluginの該当バージョンが規定するAsakusa Frameworkバージョンを導入します。詳しくは先述の asakusafwVersion を参照してください。

ThunderGateプロパティ

ThunderGateの構成に関する規約プロパティは、 asakusafwOrganizer ブロック内の参照名 thundergate でアクセスできます 19 。この規約オブジェクトは以下のプロパティを持ちます。

Framework Organizer Plugin - ThunderGateプロパティ ( thundergate ブロック )

プロパティ名

型

デフォルト値

説明

enabled

boolean

false

この値をtrueにするとThunderGate用の構成を行う

target

String

未指定

デプロイメントアーカイブに含める既定のThunderGateのターゲット名。

19

これらのプロパティは規約オブジェクト com.asakusafw.gradle.plugins.AsakusafwOrganizerPluginConvention.ThunderGateConfiguration [https://docs.asakusafw.com/0.10.3/release/gradle-plugins/com/asakusafw/gradle/plugins/AsakusafwOrganizerPluginConvention.ThunderGateConfiguration.html] が提供します。

運用環境の整備

Asakusa FrameworkとバッチアプリケーションをHadoopクラスターなどの各種サーバーにデプロイし、実行するための手順などについて説明します。

運用環境のデプロイ

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

システム構成の検討

Hadoopパラメータの設定

実行時プラグインのデプロイ

マイグレーション

運用環境マイグレーションガイド

プラットフォーム関連

特定のプラットフォームでAsakusa Frameworkを利用することに関するドキュメントです。

Amazon EMR上でAsakusa Frameworkを利用する

Asakusa FrameworkとHiveを連携して利用する

運用ツールの利用

Asakusa Frameworkが提供する運用ツールに関するドキュメントです。

ユーティリティツールユーザーガイド

関連するドキュメント

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

システム構成の検討

Hadoopパラメータの設定

実行時プラグインのデプロイ

運用環境マイグレーションガイド

Amazon EMR上でAsakusa Frameworkを利用する

Asakusa FrameworkとHiveを連携して利用する

ユーティリティツールユーザーガイド

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

この文書は、運用環境に対してAsakusa Frameworkの実行環境をセットアップする方法に関して説明します。

See also

Asakusa Framework チュートリアル [https://docs.asakusafw.com/basic-tutorial/0.10/release/ja/html/index.html] の後半にも実行環境のセットアップについて説明しています。

運用環境の準備

まず、Asakusa Frameworkの実行環境をセットアップするための運用環境を準備します。

Asakusa on MapReduce / Asakusa on Spark 実行環境

Asakusa on MapReduce や Asakusa on Spark を利用する場合には、通常は運用環境にHadoopクラスターを用意します。

Hadoopクラスターの具体的な構築手順は、利用するHadoopディストリビューションのドキュメント等を参考にして下さい。

また、SparkのセットアップはHadoopディストリビューションが提供するSparkを利用する方法や、 Apache Sparkのダウンロードサイト [http://spark.apache.org/downloads.html] からSparkの実行バイナリを入手してセットアップする方法などがあります。

Asakusa on M³BP 実行環境

Asakusa on M³BP を利用する場合には、 Asakusa on M3BPユーザーガイド - 対応プラットフォーム の「実行環境」に記載する構成を持つ環境を準備します。

Hint

Red Hat Enterprise Linux 7.2 (またはCentOS 7.2) を利用する場合、OSの初期セットアップの方法にもよりますが多くの場合 GNU C++ Library 及び GNU C Library は初期構成に含まれます。

また、Portable Hardware Localityを追加するコマンド例は以下の通りです。

yum install hwloc

Asakusa Frameworkのデプロイメント

ここでは、運用環境にAsakusa Frameworkをデプロイしてバッチアプリケーションの実行を行うまでの手順を、以下のトピックに分けて説明します。

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

デプロイメントアーカイブの配置

環境構成の確認とバッチの実行

以降の説明では、Akakusa Frameworkの開発環境でアプリケーションプロジェクトからバッチアプリケーションが作成できることを前提とします。開発環境の構築やアプリケーションプロジェクトについては、 Asakusa Framework スタートガイド や Asakusa Gradle Plugin ユーザーガイド などを参照してください。

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

Asakusa Frameworkを運用環境で利用するには、Asakusa Frameworkの「実行モジュール」一式を運用環境に配置する必要があります。

実行モジュールには、たとえば以下のようなものが含まれます。

Asakusa Framework本体の実行ライブラリ

Asakusa Frameworkで生成したバッチアプリケーション

Asakusa Frameworkのプラグインモジュール

Asakusa Frameworkの設定ファイル

Asakusa Frameworkではこれらの実行モジュールを生成する様々な方法を提供していますが、ここでは運用環境への配置が必要な全てのファイルを「デプロイメントアーカイブ」と呼ばれる単一のアーカイブファイルに含める方法について、いくつかの構成例とともに説明します。

シンプルな例

デプロイメントアーカイブの作成には、Gradleの assemble タスクを実行します。

./gradlew assemble

アプリケーションプロジェクトの標準設定でGradleの assemble タスクを実行すると、バッチアプリケーションのビルドが行われ、ビルドが成功した場合はデプロイメントアーカイブがプロジェクトの build ディレクトリ配下に asakusafw-${project.name}.tar.gz というファイル名で生成されます。

このデプロイメントアーカイブには以下のモジュールが含まれます。

Asakusa Framework本体の実行ライブラリ

プロジェクトに含まれるすべてのバッチアプリケーション

Asakusa Frameworkの標準設定の設定ファイル

プラグイン構成の追加

プロジェクトテンプレートの初期構成に対して、プラグイン構成を後から追加、削除することができます。プラグイン構成を追加するには、ビルドスクリプト上に apply plugin: <プラグインID> のように利用するプラグイン構成を追加します。

以下の設定例では、Asakusa on Spark向けのプロジェクトテンプレートに対して、 Asakusa on MapReduce用のプラグイン asakusafw-mapreduce を追加しています。

build.gradle

apply plugin: 'asakusafw-sdk'
apply plugin: 'asakusafw-organizer'
apply plugin: 'asakusafw-spark'
apply plugin: 'asakusafw-mapreduce'
apply plugin: 'eclipse'

この状態で assemble タスクを実行すると、Spark環境向けのバッチアプリケーションとMapReduce環境向けのバッチアプリケーションが生成されます。

設定ファイルの同梱

デプロイメントアーカイブに、特定の運用環境向けの設定ファイルを含めることもできます。

以下は、 プロジェクトディレクトリの src/dist/prod 配下に配置した設定ファイルをデプロイメントアーカイブに含める例です。

build.gradle

asakusafwOrganizer {
    profiles.prod {
        assembly.into('.') {
            put 'src/dist/prod'
        }
    }
}

デプロイメントアーカイブの構成を変更するには、アプリケーションプロジェクトのビルドスクリプト build.gradle の asakusafwOrganizer ブロックを編集します。

また、標準のデプロイメント構成用のプロファイルである profile.prod ブロック内の設定を編集します。プロファイルについては後述の 複数の運用環境向けのデプロイ管理 にて説明します。

assembly.into は引数に指定したパス上にファイルを含めることを意味します。例では引数に (.) と記述しており、これはデプロイメントアーカイブのルートディレクトリに対してファイルを含める指定となります。

assembly.into ブロック配下の put の引数で含める対象となるファイルパスを指定します。相対パスで指定した場合はプロジェクトディレクトリが起点となります。この例では、 src/dist/prod 配下には $ASAKUSA_HOME のディレクトリ構造と同じ形式で追加したい設定ファイルを以下のように配置しています。

src/dist/prod
 ├── core
 │   └── conf
 │       └── asakusa-resources.xml
 └── yaess
     └── conf
         └── yaess.properties

asakusafwOrganizer ブロック上では上記の他にも様々な構成に関する設定が可能です。詳しくは Asakusa Gradle Plugin ユーザーガイド や Asakusa Gradle Plugin リファレンス を参照してください。

以下は、 asakusafwOrganizer ブロック に対するいくつかの設定例を紹介します。

拡張モジュールの同梱

Asakusa Frameworkが標準のデプロイメントアーカイブに含めていない拡張モジュールを同梱する例です。

以下は、Direct I/O Hive用の実行ライブラリとWindGateのリトライ実行用の拡張プラグイン asakusa-windgate-retryable をデプロイメントアーカイブに含める例です。

build.gradle

asakusafwOrganizer {
    hive.enabled true
    windgate.retryableEnabled true
}

この例では、設定を ( profiles.prod ブロックではなく ) asakusafwOrganizer ブロックの直下に追加しているため、この設定は開発環境用のインストール構成にも適用されます。

See also

拡張モジュールの利用については、 Asakusa Gradle Plugin ユーザーガイド を参照してください。

Hiveライブラリの指定

開発環境と運用環境でDirect I/O Hive用の実行ライブラリを分ける例です。

以下は、運用環境のHadoopディストリビューションに MapR [https://www.mapr.com/] を利用する環境でDirect I/O Hiveを利用するための設定例です。

build.gradle

repositories {
    maven { url 'http://repository.mapr.com/maven/' }
}

asakusafwOrganizer {
    hive.enabled true
    profiles.prod {
        hive.libraries = ['org.apache.hive:hive-exec-1.2.0-mapr-1609@jar']
    }
}

Direct I/O Hiveを MapR [https://www.mapr.com/] 環境で利用する場合、Direct I/O HiveはMapRが提供するHiveライブラリを利用する必要があるため、運用環境用のデプロイメントアーカイブにHiveライブラリを指定しています。

Hint

MapR [https://www.mapr.com/] 用のライブラリを指定する場合、MapRライブラリ配布用のMavenリポジトリを repositories ブロックで指定する必要があります。

See also

Direct I/O Hiveについては、 Direct I/O Hive を参照してください。

外部ライブラリの配置

外部ライブラリやAsakusa Frameworkが標準で同梱しない、特別な実行時プラグインを利用する場合、 $ASAKUSA_HOME/ext/lib 配下にライブラリを配置すると利用可能になります 1 。

これらのライブラリをデプロイメントアーカイブに同梱するには、以下のように書けます。

build.gradle

asakusafwOrganizer {
    extension {
        libraries += ["com.asakusafw.sandbox:asakusa-directio-runtime-ext:${asakusafw.core.version}"]
    }
}

Attention

この機能では、指定したライブラリの推移的依存関係となるライブラリは含まれません。

Hint

リポジトリ上に存在しないライブラリを同梱したい場合には、 設定ファイルの同梱 と同様の方法でもライブラリファイルを配置することができます。

1

実行時プラグインの配置については、 実行時プラグインのデプロイ の内容も参照してください。

複数の運用環境向けのデプロイ管理

バッチアプリケーションを実行する運用環境が複数ある場合、環境ごとにデプロイ構成を変更したい場合があります。このような場合、運用環境ごとにデプロイ構成用のプロファイルを作成すると便利です。

以下は、ステージング環境用のデプロイ構成を持つデプロイメントアーカイブを作成する例です。

build.gradle

asakusafwOrganizer {
    profiles.prod {
        assembly.into('.') {
            put 'src/dist/prod'
        }
        assembly.into('.') {
            put 'src/dist/common'
            replace 'asakusa-resources.xml', inputCombineMax: '48'
        }
    }
    profiles.stage {
        assembly.into('.') {
            put 'src/dist/stage'
        }
        assembly.into('.') {
            put 'src/dist/common'
            replace 'asakusa-resources.xml', inputCombineMax: '24'
        }
    }
}

標準で設定されているプロファイル profiles.prod に加えて、ステージング環境用のプロファイルとして profiles.stage を追加しています。

この設定でデプロイメントアーカイブの生成を行うと、 build ディレクトリ配下に標準のデプロイメントアーカイブに加えて、 asakusafw-${project.name}-stage.tar.gz というファイル名で profiles.stage に対応したデプロイメントアーカイブが生成されます。

この例では、それぞれのプロファイル用に作成した設定ファイル用のディレクトリ( src/dist/prod, src/dist/stage )から設定ファイルを配置しています。

また、それぞれのプロファイルに共通の設定ファイルを管理するディレクトリ( src/dist/common )からも設定ファイルを配置しています。このとき、 replace 句を指定することで設定ファイルの内容を置換して、環境ごとに固有のパラメータを設定しています。

例えば、 src/dist/common 配下に asakusa-resources.xml を以下のような内容で配置します。

asakusa-resources.xml

<?xml version="1.0" encoding="UTF-8"?>
<?xml-stylesheet type="text/xsl" href="configuration.xsl"?>
<configuration>
    ...
    <property>
        <name>com.asakusafw.input.combine.max</name>
        <value>@inputCombineMax@</value>
    </property>
</configuration>

build.gradle では以下のように設定しているため、

profile.prod ブロック: replace 'asakusa-resources.xml', inputCombineMax: '48'

profile.stage ブロック: replace 'asakusa-resources.xml', inputCombineMax: '24'

それぞれのデプロイメントアーカイブの asakusa-resources.xml にはこれらの設定値が置換された状態の設定ファイルが同梱されます。

See also

Amazon EMR上でAsakusa Frameworkを利用する でも運用環境向けのデプロイ機能の利用例を紹介しています。デプロイ構成を柔軟に設定できるこれらの機能は、クラウド環境上で様々な運用環境を構築する場合などでも効果的でしょう。

デプロイメントアーカイブの配置

デプロイメントアーカイブの作成 で作成したデプロイメントアーカイブを運用環境に配置します。

以降では、Asakusa on SparkとAsakusa on MapReduce向けのバッチアプリケーションを実行するために、Hadoopクラスターに配置する例を説明します。

また、ここでは運用環境上に構築したHadoopクラスターの各ノードうち、Asakusa Frameworkを配置してバッチアプリケーションの実行操作を行うノードを「Hadoopクライアントマシン」と呼びます。

環境変数の設定

Hadoopクライアントマシン上でAsakusa Frameworkを配置しバッチアプリケーションの実行操作を行うOSユーザーに対して、以下の環境変数を設定します。

JAVA_HOME: YAESSが使用するJavaのインストールパス

HADOOP_CMD: YAESSが使用する hadoop コマンドのパス

SPARK_CMD: YAESSが使用する spark-submit コマンドのパス

ASAKUSA_HOME: Asakusa Frameworkのインストールパス

~/.profile をエディタで開き、最下行に以下の定義を追加します。

.profile

export JAVA_HOME=/usr/lib/jvm/java-8-oracle
export HADOOP_CMD=/usr/lib/hadoop/bin/hadoop
export SPARK_CMD=/opt/spark/bin/spark-submit
export ASAKUSA_HOME=$HOME/asakusa

~/.profile を保存した後、設定した環境変数をターミナル上のシェルに反映させるため、以下のコマンドを実行します。

. ~/.profile

Attention

実際に必要となる環境変数は利用するコンポーネントや構成によって異なります。これらの詳細はAsakusa Frameworkの各コンポーネントのドキュメントを参照してください

デプロイメントアーカイブの展開

Hadoopクライアントマシンにデプロイメントアーカイブファイル asakusafw-${project.name}.tar.gz を配置し、 $ASAKUSA_HOME 配下にデプロイメントアーカイブを展開します。展開後、 $ASAKUSA_HOME 配下の *.sh に実行権限を追加します。展開後 $ASAKUSA_HOME/tools/bin/setup.jar を実行し、展開したファイルに対して適切な実行権限などを設定します。

mkdir -p "$ASAKUSA_HOME"
cd "$ASAKUSA_HOME"
tar -xzf /path/to/asakusafw-*.tar.gz
java -jar $ASAKUSA_HOME/tools/bin/setup.jar

Attention

$ASAKUSA_HOME/tools/bin/setup.jar を実行する手順は Asakusa Framework バージョン 0.10.0 より追加されました。

バージョン 0.9以前では、この部分は find "$ASAKUSA_HOME" -name "*.sh" | xargs chmod u+x のようなコマンドを実行していましたが、バージョン 0.10.0 から展開後のファイル拡張子が変更されたため、この手順では正しくセットアップすることができません。

そのためバージョン 0.10.0 以降は必ず上記のように $ASAKUSA_HOME/tools/bin/setup.jar を実行してセットアップを行ってください。

See also

setup.jar の詳細は、 ユーティリティツールユーザーガイド を参照してください。

環境構成の確認とバッチの実行

運用環境にデプロイしたAsakusa Frameworkのバッチアプリケーションを以下の手順で実行して運用環境上の動作確認を行います。

動作確認用テストデータの配置

バッチアプリケーションの実行

バッチアプリケーションの実行結果の確認

ここでは、 Asakusa Framework スタートガイド で紹介したDirect I/O をを使ったサンプルアプリケーションをAsakusa Frameworkの標準設定のままで実行する例を示します。

動作確認用テストデータの配置

バッチアプリケーションの実行に必要な入力データを配置します。

以下は、Hadoopクライアントマシン上に配置した入力データファイルを hadoop コマンドでHadoopファイルシステムに登録する例です。

hadoop fs -put /path/to/example-dataset/master target/testing/directio/master
hadoop fs -put /path/to/example-dataset/sales target/testing/directio/sales

Hint

実行するバッチアプリケーションが利用する外部システム連携機能によって、入力データの配置箇所は異なります。例えば、WindGate/JDBC を利用する場合はデータベースに対して入力データを配置します。

Hint

Asakusa on M³BP を標準の設定で利用する場合、Direct I/Oのファイルシステムパスは通常OS標準のファイルシステムに対応します。

このため、入力データを配置する例は以下のようになります。

mkdir -p "$HOME/target/testing/directio"
cp -a /path/to/example-dataset/master $HOME/target/testing/directio/master
cp -a /path/to/example-dataset/sales $HOME/target/testing/directio/sales

なお、 Asakusa on M³BP をHadoopファイルシステムと連携して利用する方法については、 Asakusa on M3BPユーザーガイド の「Hadoopとの連携」の項を参照してください。

バッチアプリケーションの実行

デプロイしたバッチアプリケーションをYAESSを使って実行します。

$ASAKUSA_HOME/yaess/bin/yaess-batch.sh コマンドに実行するバッチIDとバッチ引数を指定してバッチを実行します。

Asakusa on MapReduce を利用したバッチアプリケーションの場合、バッチIDをそのまま指定して実行します。

$ASAKUSA_HOME/yaess/bin/yaess-batch.sh example.summarizeSales -A date=2011-04-01

Asakusa on Spark を利用したバッチアプリケーションの場合、バッチIDのプレフィックスに spark. を付与して実行します。

$ASAKUSA_HOME/yaess/bin/yaess-batch.sh spark.example.summarizeSales -A date=2011-04-01

Asakusa on M3BP を利用したバッチアプリケーションの場合、バッチIDのプレフィックスに m3bp. を付与して実行します。

$ASAKUSA_HOME/yaess/bin/yaess-batch.sh m3bp.example.summarizeSales -A date=2011-04-01

バッチの実行が成功すると、コマンドの標準出力の最終行に Finished: SUCCESS と出力されます。

2013/04/22 13:50:35 INFO  [YS-CORE-I01999] Finishing batch "example.summarizeSales": batchId=example.summarizeSales, elapsed=12,712ms
2013/04/22 13:50:35 INFO  [YS-BOOTSTRAP-I00999] Exiting YAESS: code=0, elapsed=12,798ms
Finished: SUCCESS

バッチの実行が失敗した場合はYAESSのログを確認します。

バッチアプリケーションのシミュレーションモード実行

YAESSでは実際のアプリケーションの実行は行わず、環境構成や設定の確認のみを行うシミュレーションモード実行を行うことができます。

この機能は、バッチの失敗が環境構成や設定の問題であるか、アプリケーション内の問題であるかを切り分けるために有効です。

バッチをシミュレーションモードで実行するには、 yaess-batch.sh コマンドの引数の末尾に -D dryRun と指定します。

$ASAKUSA_HOME/yaess/bin/yaess-batch.sh example.summarizeSales -A date=2011-04-01 -D dryRun

バッチアプリケーションの実行結果の確認

バッチアプリケーションが出力したデータの内容を確認します。

Direct I/O をバッチの出力に利用するアプリケーションについては、以下のツールなどを利用してファイルシステム上のファイル内容を確認することができます。

$ASAKUSA_HOME/directio/bin/list-file.sh <base-path> <resource-pattern>

Direct I/Oの入出力ディレクトリやファイルの一覧を表示

hadoop fs -text <file-path>

Hadoopファイルシステム上の指定したファイルパスの内容を表示

関連するトピック

運用環境の構築や設定に関する情報として、以下のドキュメントも参考にしてください。

実行エンジンの最適化に関する設定

以下のドキュメントでは、各実行環境のチューニングパラメータなどを説明しています。

Hadoopパラメータの設定

Asakusa on Sparkの最適化設定

Asakusa on M3BPの最適化設定

各コンポーネントの設定

Asakusa Frameworkの各コンポーネントの設定に関しては、各コンポーネントのユーザーガイドなどを参照してください。

Direct I/O ユーザーガイド

WindGateユーザーガイド

YAESSユーザーガイド

また、外部システム連携モジュールを用いた場合のシステム構成に関して以下のドキュメントで紹介しています。

システム構成の検討

システム構成の検討

この文書では、Asakusa Frameworkの運用環境におけるシステム構成例について説明します。

用語の定義

本書では、マシン構成に関しての用語を以下のように定義します。

マシン

それぞれのコンピューターを表します。仮想化されたコンピューターであっても構いません。

モジュール

特定の役割を持ったソフトウェアです。いくつかのコンポーネントを組み合わせて構成します。

コンポーネント

Asakusa Frameworkのそれぞれのコンポーネントです。 Asakusa Frameworkコア 1 や、YAESS、WindGateなどがコンポーネントの単位となります。

1

現在のところ、Direct I/Oに関するライブラリやツールはすべてAsakusa Frameworkコアに含まれています。

モジュール

以下は本ガイドで紹介するモジュール群です。それぞれのマシンに機能を割り当て、それを実現するモジュールを配置していく形になります。

Hadoopクライアントモジュール

Hadoopのジョブ起動や、Hadoopのファイルシステムにアクセスを行うモジュールです 2 3 。

外部システム連携モジュール

外部システムとHadoopクラスター間でデータをやり取りするためのモジュールです 4 。

バッチ起動モジュール

Asakusa Frameworkで開発したAsakusaバッチアプリケーションを起動するためのモジュールです。

ひとつのマシン上に複数のモジュールを配置することもできます。モジュールが異なるマシン上に存在する場合、SSHやRPCなどの適切なプロトコルを利用して処理を行います。

2

Hadoopの動作上、Hadoopのジョブを起動するノードからもデータストアへのアクセスが行われます。共有ディスクなどを利用する場合は、このHadoopクライアントモジュールを配置したマシンについてもHadoopスレーブノードと同様の方法で対象のデータストアを参照できる必要があります。

3

Hadoopのマスターノードやスレーブノード上にクライアントモジュールを配置することもできます。

4

外部システム連携モジュールはシステム上に複数用意することもできます。

コンポーネント

以下は本書でデプロイする対象のコンポーネント群です。モジュールごとに利用するコンポーネントは異なります。モジュールを配置したマシンごとに必要なコンポーネントをデプロイしていく形になります。

Asakusaバッチアプリケーション

Asakusa Frameworkで作成したアプリケーションです。 Hadoopクライアントモジュール、外部システム連携モジュール、バッチ起動モジュールのそれぞれが利用します。

Asakusa Frameworkコア

Asakusa Framework本体です。 Hadoopクライアントモジュール、外部システム連携モジュール、バッチ起動モジュールのそれぞれが利用します。

WindGate

WindGate 本体です。外部システム連携モジュールが利用します。

WindGate Hadoopブリッジ

WindGateがHadoopと通信するために中継するソフトウェアです。 Hadoopクライアントモジュールが利用します。

外部システム連携モジュールとHadoopクライアントモジュールが同じマシン上に配置されている場合、WindGate Hadoopブリッジは不要です。この場合、WindGateはHadoopブリッジを経由せず、Hadoopファイルシステムに直接アクセスします。

YAESS

YAESS 本体です。バッチ起動モジュールが利用します。

YAESS Hadoopブリッジ

YAESSがHadoopと通信するために中継するソフトウェアです。 Hadoopクライアントモジュールが利用します。

Direct I/Oのシステム構成

Direct I/Oを用いた場合のシステム構成について、いくつか例を見ていきます。

シンプルな構成例

Direct I/Oを利用したシンプルな構成例を以下に示します。

上記の構成では、Hadoopクライアントモジュールとバッチ起動モジュールをそれぞれ同じマシン（Hadoopクライアントマシン）上に配置しています。各モジュール間の通信は単一のマシン内で行われ、HadoopクライアントモジュールはHadoop APIを介してHadoopクラスター上のサービスにアクセスします。

下図は、この構成でHadoopクライアントマシンが利用するコンポーネントの一覧です。

バッチ起動を外部から行う場合の構成例

バッチの起動を行う「ゲートウェイマシン」をHadoopクライアントマシンとは別に用意した場合の構成例を以下に示します。

ゲートウェイマシンはHadoopクライアントマシン上の各種HadoopブリッジとSSHを利用して通信します。そのため、あらかじめゲートウェイマシンからHadoopクライアントマシンにSSH経由（公開鍵認証）でアクセスできるようにしておく必要があります。

下図は、この構成でゲートウェイマシンが利用するコンポーネントの一覧です。

同様に、下図はHadoopクライアントマシンが利用するコンポーネントの一覧です。

Hint

この構成の利点は、ゲートウェイマシンとHadoopクライアントマシンに異なるセキュリティレベルを設定できる点です。ゲートウェイマシン から Hadoopクライアントマシンに対してSSHでログイン出来ればよく、HadoopクラスターやHadoopクライアントマシンに不正侵入されても、そこからゲートウェイマシンに侵入するにはもう一手間必要です。

WindGateのシステムの構成

WindGateを用いた場合のシステム構成について、いくつか例を見ていきます。

WindGate/CSVによるシンプルな構成例

WindGateをローカルのCSVファイルと連携する構成における、シンプルな構成例を以下に示します。

上記の構成では、Hadoopクライアントモジュール、外部システム連携モジュール、バッチ起動モジュールをそれぞれ同じマシン（Hadoopクライアントマシン）上に配置しています。各モジュール間の通信はマシン内で行われ、HadoopクライアントモジュールはHadoop APIを介してHadoopクラスター上のサービスにアクセスします。

下図は、この構成でHadoopクライアントマシンが利用するコンポーネントの一覧です。

Hint

Hadoopクライアントモジュールと外部システム連携モジュールが同一のマシン上に存在するため、WindGate Hadoopブリッジは不要です。

Hint

WindGateはローカルファイル上のCSVファイルに対する入出力の仕組みを提供します。 WindGateのCSV機能を利用する外部システムは、WindGate(外部システム連携モジュール)がデプロイされているマシン上に対して処理対象となるCSVファイルを配置したり、取り込む仕組みを用意する必要があります。

WindGate/RDBMSによるHadoopブリッジを使った構成例

WindGateをRDBMSと連携し、かつHadoopクライアントモジュールと外部システム連携モジュールが異なる場合の構成例を以下に示します。

上記の構成では、前述のHadoopクライアントマシンのほかに、ゲートウェイマシンを導入しています。ゲートウェイマシンはデータベースとJDBCを利用して通信し、Hadoopクライアントマシン上の各種HadoopブリッジとはSSHを利用して通信しています。そのため、以下の準備があらかじめ必要です。

ゲートウェイマシンからデータベースにJDBC経由でアクセスできるようにする

ゲートウェイマシンからHadoopクライアントマシンにSSH経由（公開鍵認証）でアクセスできるようにする

下図は、この構成でゲートウェイマシンが利用するコンポーネントの一覧です。

同様に、下図はHadoopクライアントマシンが利用するコンポーネントの一覧です。

Hint

この構成の利点は、ゲートウェイマシンとHadoopクライアントマシンに異なるセキュリティレベルを設定できる点です。ゲートウェイマシン から Hadoopクライアントマシンに対してSSHでログイン出来ればよく、HadoopクラスターやHadoopクライアントマシンに不正侵入されても、そこからゲートウェイマシンに侵入するにはもう一手間必要です。データベースやバッチの起動部分を保護するという点では重要な意味合いがあります。

Hadoopパラメータの設定

この文書では、HadoopのパラメータのうちAsakusa Framework特有のものについて説明します。

設定ファイル

Asakusa Frameworkに関するHadoopのパラメータは、 $ASAKUSA_HOME/core/conf/asakusa-resources.xml 1 に設定します。このファイルに設定した内容はバッチアプリケーションの実行時にHadoopジョブの設定として使用され、ジョブ実行時の動作に影響を与えます。また、Hadoopのライブラリを利用している データの直接入出力 - Direct I/O などの設定もこのファイルに記述します。

設定ファイルはHadoopの各設定ファイルのフォーマットと同様です。以下のように、１つの設定項目に対して <property> 要素を作成し、設定名を <name> 要素に、設定値を <value> 要素にそれぞれ設定します。

asakusa-resources.xml

<configuration>
    <property>
        <name>(設定名1)</name>
        <value>(設定値1)</value>
    </property>
    <property>
        <name>(設定名2)</name>
        <value>(設定値2)</value>
    </property>
    <!-- 以下、繰り返し -->
</configuration>

1

このファイルは、 実行時プラグインの設定 と共有しています。

Hint

上記の設定は、 YAESSのHadoopのプロパティ設定 でも一部設定が可能です。

設定項目

Hadoopパラメータで設定可能な項目は、以下のドキュメントを参照してください。

Direct I/O ユーザーガイド

MapReduceタスクの最適化設定

ライブラリキャッシュの設定

実行時プラグインのデプロイ

実行時プラグインのデプロイ

この文書では、Asakusa Frameworkの実行時プラグインのデプロイ方法について説明します。

実行時プラグインについて

実行時プラグインとは、Asakusa FrameworkのフレームワークAPIを拡張するための内部機構です。バッチアプリケーションがAsakusa Frameworkが標準で提供していない、個別の拡張フレームワークAPIを使用している場合は、以下に説明する手順に従って、実行時プラグインのデプロイを行ってください。

実行時プラグイン用ライブラリの配置

実行時プラグイン用ライブラリはjarファイルとして提供されます。実行時プラグイン用のjarファイルは $ASAKUSA_HOME/ext/lib ディレクトリに配置してください。

デプロイメントアーカイブの生成時に実行時プラグイン用のjarファイルを同梱することもできます。 Asakusa Framework デプロイメントガイド - 外部ライブラリの配置 の例などを参考にしてください。

実行時プラグインの設定

実行時プラグインの設定ファイルを編集します。

実行時プラグインの設定は、 $ASAKUSA_HOME/core/conf/asakusa-resources.xml を編集します。以下のように、それぞれの設定項目に対して <property> 要素を作成し、設定名を <name> 要素に、設定値を <value> 要素にそれぞれ設定します。

asakusa-resources.xml

<configuration>
    <property>
        <name>com.asakusafw.runtime.core.Report.Delegate</name>
        <value>com.asakusafw.runtime.core.Report$Default</value>
    </property>
    <property>
        <name>com.asakusafw.runtime.extention.HogeRuntimePlugin.Delegate</name>
        <value>com.asakusafw.runtime.extention.HogeRuntimePlugin$Default</value>
    </property>
</configuration>

レポートAPIに関するプラグイン

レポートAPIは実行時プラグインの仕組みを利用して実装されており、レポートAPIの実装を自由に差し替えることが可能です。レポートAPIは Report.Delegate 1 インターフェースを実装したクラスを利用して自由に実装を変更できます。

レポートAPIの実装クラスは、実行時プラグインの設定に対し、 com.asakusafw.runtime.core.Report.Delegate という設定名で設定値に実装クラスの完全限定名を指定します。

Asakusa Frameworkは以下の実装クラスを組み込みで提供しています。

レポートAPIの組み込み実装クラス

クラス名

概要

com.asakusafw.runtime.core.Report$Default 2

標準出力にレポートを出力する実装。

com.asakusafw.runtime.report.CommonsLoggingReport 3

Commons Loggingを経由してレポートを出力する実装。 Hadoop上で実行する場合、Hadoopのログの設定を変更することで出力先等を設定可能。

レポートAPIの利用方法については Asakusa DSLユーザーガイド を参照してください。

1

com.asakusafw.runtime.core.Report.Delegate [https://docs.asakusafw.com/0.10.3/release/api/com/asakusafw/runtime/core/Report.Delegate.html]

2

com.asakusafw.runtime.core.Report.Default [https://docs.asakusafw.com/0.10.3/release/api/com/asakusafw/runtime/core/Report.Default.html]

3

com.asakusafw.runtime.report.CommonsLoggingReport [https://docs.asakusafw.com/0.10.3/release/api/com/asakusafw/runtime/report/CommonsLoggingReport.html]

運用環境マイグレーションガイド

この文書では、Asakusa Framework のバージョンアップに伴う、運用環境のマイグレーション手順について解説します。

バージョン共通のマイグレーション手順

ここでは、各バージョン共通のマイグレーション手順について説明します。

Attention

ここで説明する手順に加えて、マイグレーション先のバージョンや現在利用している環境によっては、後述する バージョン固有のマイグレーション手順 が必要となる場合があるので必ずその内容も確認してください。

デプロイメントアーカイブの再配置

運用環境のマイグレーションを行う場合、アプリケーションプロジェクトに対してマイグレーション対象バージョンでビルドしてデプロイメントアーカイブを再作成して、運用環境にデプロイメントアーカイブを再配置します。

運用環境のデプロイについては、以下のドキュメントを参照してください。

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

Attention

Asakusa Frameworkのマイグレーションを行う際には、基本的にマイグレーション対象のバージョンでコンパイルを行ったバッチアプリケーションをデプロイする必要があります。

マイグレーション元となるバージョンでビルドしたバッチアプリケーションをマイグレーション先の環境にデプロイしないよう注意してください。

Hint

各コンポーネントで利用する運用環境向けの設定ファイルについては、アプリケーションプロジェクトのビルド設定やプロファイルを利用して管理することを推奨します。

デプロイメントの構成については、 Asakusa Framework デプロイメントガイド や Asakusa Gradle Plugin ユーザーガイド を参照してください。

バージョン固有のマイグレーション手順

バージョン 0.9.0 へのマイグレーション

Java (JDK)

Java7、およびJDK 7は非対応になりました。

Java7、およびJDK 7を利用している場合、Java8 (JDK 8)に移行する必要があります。

運用環境で利用可能なJavaのバージョンや移行方法については、利用しているHadoopディストリビューションのドキュメントなどを参照してください。

Spark

Spark 1.6 以前のバージョンは非対応になりました。

Spark 1.6、およびそれ以前のバージョンを利用している場合、Spark 2.0 以降のバージョンに移行する必要があります。

Spark 2.0 への移行については、Sparkのドキュメント、または利用しているHadoopディストリビューションのドキュメントなどを参照してください。

バージョン 0.8.0 へのマイグレーション

Java (JDK)

Java6、およびJDK 6は非対応になりました。

Java6、およびJDK 6を利用している場合、Java 7(JDK 7)、またはJava8 (JDK 8)に移行する必要があります。

運用環境で利用可能なJavaのバージョンや移行方法については、利用しているHadoopディストリビューションのドキュメントなどを参照してください。

Hadoop

Hadoop1系は非対応となりました。

運用環境でHadoop1系を利用している場合、Hadoop2系に移行してください。

Hadoop2系への移行については、利用しているHadoopディストリビューションのドキュメントなどを参照してください。

Amazon EMR上でAsakusa Frameworkを利用する

対象バージョン: Asakusa Framework 0.9.0 以降

この文書は、 Amazon Web Services [http://aws.amazon.com/] (AWS) が提供するクラウド環境上のHadoopサービス Amazon EMR [http://aws.amazon.com/emr/] 上でAsakusa Frameworkを利用する方法について説明します。

Attention

Amazon EMR [http://aws.amazon.com/emr/] は頻繁にバージョンアップが行われるため、バージョンによっては本書と内容が異なる可能性があります。

以降では、 Amazon Web Services [http://aws.amazon.com/] を「AWS」、 Amazon EMR [http://aws.amazon.com/emr/] を「EMR」と表記します。

また、本書ではAsakusa Frameworkのデプロイやアプリケーションの実行時に、AWSが提供するストレージサービスである Amazon Simple Storage Service [http://aws.amazon.com/s3/] （Amazon S3）を利用します。以降では、 Amazon Simple Storage Service [http://aws.amazon.com/s3/] を「S3」と表記します。

AWSが提供する各サービスの詳細はAWSが提供するドキュメントを参照してください。

はじめに

本書では、 Asakusa Framework スタートガイド の説明で使用したサンプルアプリケーションを例に、EMR上でバッチアプリケーションを実行するまでの手順を説明します。

また、ここではアプリケーションのデータ入出力をS3に対して行うよう設定します。

EMRと関連サービス利用環境の準備

EMRやS3を利用するための環境を準備します。

本書で示す手順に従ってEMR上でAsakusa Frameworkを利用するためには、以下の準備を行う必要があります。

AWSへのサインアップ

Amazon S3バケットの作成

これらの準備が整っていない場合、以下に示すドキュメントなどを参考にして、EMRを利用するための環境を準備してください。

AWSへのサインアップ

アカウント作成の流れ | アマゾン ウェブ サービス（AWS 日本語） [http://aws.amazon.com/jp/register-flow/]

Amazon S3バケットの作成

Amazon Simple Storage Service の使用開始 [http://docs.aws.amazon.com/ja_jp/AmazonS3/latest/gsg/GetStartedWithS3.html] ( Amazon S3 入門ガイド [http://docs.aws.amazon.com/ja_jp/AmazonS3/latest/gsg/GetStartedWithS3.html] )

AWSサービスの操作

EMRやS3など、AWSが提供する各サービスに対する操作には以下のような方法があります。

AWSマネジメントコンソール [http://aws.amazon.com/jp/console/] (以下「コンソール」)を使用する方法

AWSコマンドラインインターフェイス [http://aws.amazon.com/jp/cli/] (以下「CLI」)を使用する方法

AWSが提供するSDKを利用する方法

各サービスが提供するWeb Service APIを利用する方法

それぞれのツールで実現可能な操作が多少異なりますが、本書の範囲内ではコンソールやCLIですべての操作が可能です。本書では操作手順の説明においてコンソールとCLIの操作を簡単に紹介します。

AWSで利用可能な操作の詳細やツールのセットアップ方法などは、各サービスのドキュメントを参照してください。

Asakusa Framework実行環境の構成とデプロイ

開発環境で作成したアプリケーションプロジェクトに対してEMR環境向けにAsakusa Frameworkの構成を行い、Asakusa Framework実行環境一式をデプロイします。

EMRを利用する上では、様々な方法でAsakusa Frameworkをデプロイすることができますが、ここではAsakusa FrameworkのデプロイメントアーカイブをEMRクラスター 1 の起動前にS3に配置し、EMRクラスターの起動後にこれをEMRクラスターのマスターノードにデプロイするものとします。

1

Amazon EMR Management Guide [http://docs.aws.amazon.com/ElasticMapReduce/latest/ManagementGuide/] の記述に基づき、EMRを利用して構築したクラスター環境をEMRクラスターと呼びます

Direct I/Oの設定

バッチアプリケーションに対してEMR上でS3に対するデータ入出力を行うための設定を行います。

Direct I/Oを使ってS3に対してデータの読み書きを行うようにするため設定ファイル asakusa-resources.xml を編集します。

以下は、 asakusa-resources.xml の設定例です。

asakusa-resources.xml

<?xml version="1.0" encoding="UTF-8"?>
<?xml-stylesheet type="text/xsl" href="configuration.xsl"?>
<configuration>
    <property>
        <name>com.asakusafw.runtime.core.Report.Delegate</name>
        <value>com.asakusafw.runtime.report.CommonsLoggingReport</value>
    </property>

    <!-- task optimization -->
    <property>
        <name>com.asakusafw.input.combine.max</name>
        <value>256</value>
    </property>
    <property>
        <name>com.asakusafw.input.combine.tiny.limit</name>
        <value>1048576</value>
    </property>
    <property>
        <name>com.asakusafw.reducer.tiny.limit</name>
        <value>1048576</value>
    </property>

    <!-- library cache -->
    <property>
        <name>com.asakusafw.launcher.cache.path</name>
        <value>target/libcache</value>
    </property>

    <!-- Direct I/O base settings -->
    <property>
        <name>com.asakusafw.directio.root</name>
        <value>com.asakusafw.runtime.directio.hadoop.HadoopDataSource</value>
    </property>
    <property>
        <name>com.asakusafw.directio.root.path</name>
        <value>/</value>
    </property>
    <property>
        <name>com.asakusafw.directio.root.fs.path</name>
        <value>@directioRootFsPath@</value>
    </property>

    <!-- Direct I/O settings for EMR/S3 -->
    <property>
         <name>com.asakusafw.directio.root.output.staging</name>
         <value>false</value>
    </property>
</configuration>

See also

asakusa-resources.xml で記述するDirect I/Oの設定について詳しくは、 Direct I/O ユーザーガイド を参照してください。

また、上記の設定ファイルの例ではDirect I/O以外にいくつかの実行時設定を行なっています。詳しくは、 Hadoopパラメータの設定 を参照してください。

ここでは上記の asakusa-resources.xml をダウンロードして、アプリケーションプロジェクト配下のディレクトリ src/dist/emr/core/conf に配置してください。

mkdir -p src/dist/emr/core/conf
cp $HOME/Downloads/asakusa-resources.xml src/dist/emr/core/conf

Hint

上記設定に含まれる @...@ の文字列は、 Framework Organizer Plugin の機能を利用してデプロイメントアーカイブ作成時に環境に合わせた値に置換します。

上記の設定ファイルの例では、プロパティ com.asakusafw.directio.root.fs.path の値 @directioRootFsPath@ はデータ入出力に利用する、S3上のパスに置換します。詳しくは次項を参照してください。

デプロイメント構成の設定

EMR向けの構成を持つデプロイメントアーカイブを作成するための設定を行います。

See also

デプロイメントアーカイブやデプロイメント構成の編集について詳しくは、 Asakusa Framework デプロイメントガイド を参照してください。

ここでは、サンプルアプリケーションのプロジェクトにEMR向けのデプロイメント構成用のプロファイル emr を作成するためビルドスクリプト build.gradle を編集します。

build.gradle

asakusafwOrganizer {
    profiles.emr {
        assembly.into('.') {
            put 'src/dist/emr'
            replace 'asakusa-resources.xml', directioRootFsPath: 's3://[mybucket]/app-data'
        }
    }
}

Attention

上記例を参考に設定ファイルを作成する際は、必ず directioRootFsPath の値を実際に使用するS3バケットのパスに置き換えてください。

ここでは標準の設定に対して、EMR向けのプロファイルとして profiles.emr ブロックを追加しています。

assembly.into('.') 配下は先述の Direct I/Oの設定 で説明した設定ファイルを put によってデプロイメント構成に加えています。このとき、 asakusa-resources 内で定義したDirect I/O のファイルシステムパスの値 directioRootFsPath を指定したS3バケット上のパスに置換するための設定を定義しています。

directioRootFsPath の値は、アプリケーションのデータ入出力を行うS3バケット上のパスになります。使用する環境に応じて、適切なパスに変更してください。特にバケット名の部分( [mybucket] )は必ず変更する必要があります。

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

Akakusa Frameworkの実行環境一式を含むデプロイメントアーカイブを作成します。

デプロイメントアーカイブを作成するには、アプリケーションプロジェクト上でGradleの assemble タスクを実行します。

./gradlew assemble

デプロイメント構成の設定 を行った状態でデプロイメントアーカイブの生成を行うと、 build ディレクトリ配下に標準のデプロイメントアーカイブに加えて、 asakusafw-$project.name-emr.tar.gz というファイル名で emr プロファイルに対応したデプロイメントアーカイブが生成されます。

デプロイメントアーカイブをS3に配置

デプロイメントアーカイブの生成 で作成したデプロイメントアーカイブファイル asakusafw-$project.name-emr.tar.gz をS3に配置します。

コンソール

S3に対するファイルアップロードは AWSマネジメントコンソール [http://aws.amazon.com/jp/console/] から実行することができます。

コンソールを使ってS3にファイルをアップロードする手順の例は、 バケットにオブジェクトを追加 [http://docs.aws.amazon.com/ja_jp/AmazonS3/latest/gsg/PuttingAnObjectInABucket.html] ( Amazon S3 入門ガイド [http://docs.aws.amazon.com/ja_jp/AmazonS3/latest/gsg/GetStartedWithS3.html] ) などを参照してください。

CLI

S3に対するファイルアップロードはAWS CLIからも実行することができます。

以下AWS CLIによるファイルアップロードの例です。

aws s3 cp build/asakusafw-example-basic-spark-emr.tar.gz s3://[mybucket]/asakusafw/

S3上のファイルを表示し、正しくアップロードされたことを確認します。

aws s3 ls s3://[mybucket]/asakusafw/

Attention

上記例を参考にコマンドを入力する際は、必ずアップロード先のS3バケットのパスを実際に使用するパスに置き換えてください。

EMRクラスターの起動と確認

EMRを利用したHadoopクラスターのセットアップと動作確認を行います。

EMRクラスターの起動

コンソール

AWSマネジメントコンソール [http://aws.amazon.com/jp/console/] からEMRクラスターを起動することができます。

AWSマネジメントコンソール [http://aws.amazon.com/jp/console/] の画面左上のメニューから Services ‣ EMR を選択する。

EMRのクラスターリスト画面で、画面上部の クラスターを作成 ボタンを押下する。

EMRクラスターの起動パラメータを入力する

コンソールで指定する起動パラメータについては、 後述の 起動パラメータ で説明しているのでこちらも参照してください。

画面下の クラスターを作成 ボタンを押下する。

EMRクラスターの起動処理が開始され、クラスター詳細画面が表示されます。

CLI

EMRクラスターの起動はAWS CLIから実行することができます。

以下AWS CLIによるEMRクラスター起動の例です。

aws emr create-cluster \
 --name asakusafw-cluster \
 --log-uri s3://[mybucket]/mylog \
 --enable-debugging \
 --release-label emr-5.2.0 \
 --applications Name=Hadoop Name=Hive Name=Spark \
 --instance-type m3.xlarge \
 --instance-count 1 \
 --ec2-attributes KeyName=[myKey]

起動パラメータ

EMRクラスターの起動パラメータ（オプション）の概要を説明します。起動パラメータの詳細やここに記載していないパラメータについては、コンソールのヘルプやEMRのドキュメントなどを参照してください。

各パラメータは以下の表記で説明しています。

コンソール上の項目名 (--CLIのオプション名 )

クラスター名 (--name)

EMRクラスター名です。この名前はコンソールやCLIから参照するクラスター一覧などで表示されます。

ログ記録(S3フォルダー) (--log-uri)

このオプションを有効にすると、EMRクラスターの各ノードのログを定期的な間隔(およそ5分ごと)でS3にコピーする機能が有効になります。ログを配置するS3バケット上のパスを合わせて指定します。

デバッグ (--enable-debugging | --no-enable-debugging)

このオプションを有効にすると、コンソール上から各ログファイルを参照するためのインデックスが生成されます。

起動モード (--auto-terminate | --no-auto-terminate)

起動モードに「クラスター」 (--no-auto-terminate) を指定した場合は明示的にEMRクラスターを停止させるまでクラスターは起動し続けます。「ステップ実行」 (--auto-terminate) を指定した場合は、EMRクラスター起動時に指定したステップ(EMRクラスターで実行させる処理、詳細は後述) の実行が完了すると、自動的にEMRクラスターは停止します。 CLIを利用する場合、これらのオプションを指定しない場合は --no-auto-terminate がデフォルトで設定されます。

リリース (--release-label)

EMRクラスターのリリースバージョンを指定します。指定可能なバージョンについては Amazon EMR Release Guide [http://docs.aws.amazon.com/ElasticMapReduce/latest/ReleaseGuide/] などを参照してください。

アプリケーション (--applications)

EMRクラスターに含めるアプリケーションを指定します。このドキュメントではAsakusa on Sparkを利用するため、Sparkが含まれる項目を指定してください。

インスタンスタイプ (--instance-type)

EMRクラスターで使用するインスタンスタイプを指定します。

インスタンス数 (--instance-count)

EMRクラスターで使用するインスタンス数を指定します。

Hint

デプロイメント構成の確認やアプリケーションとの疎通確認など、試験的に実行する段階ではインスタンスタイプは低コストで利用できるインスタンスタイプを使用し、ノード数も少なめで確認するのがよいでしょう。

EC2 キーペア (--ec2-attributes KeyName=[key-name])

EMRクラスターの各ノードにSSH接続するためのキーペアを指定します。デフォルトではキーペアの指定がありません。 SSH接続を行う場合は、このオプションを指定します。

クラスターID

EMRクラスターの起動を実行すると、コンソールやCLIの出力としてクラスターを一意に特定するためのクラスターIDが出力されます。

CLI

{
    "ClusterId": "j-XXXXXXXXXXXXX"
}

CLIではEMRクラスターに対する処理を行う際に、このIDを指定します。

ステータスの確認

コンソールやCLIからEMRクラスターのステータスを確認することができます。

コンソール

EMRクラスターの起動 後に表示されるクラスター詳細画面などで確認します。

クラスター詳細画面では、画面上部 クラスター: <クラスター名> の右側に色付きの文字列で表示されます ( 下例では 開始中 ) 。

CLI

以下はAWS CLIでクラスターのステータスを取得する例です。

aws emr describe-cluster --cluster-id j-XXXXXXXXXXXXX \
 --query 'Cluster.Status.State'

"WAITING"

Hint

上記例の --query オプションによって全体の出力から結果ステータスの項目を抽出しています。

aws コマンドには他にも様々なオプションが利用できます。詳しくは AWS CLI Reference の Command Reference [http://docs.aws.amazon.com/cli/latest/index.html] などを参照してください。

主なステータスには以下のようなものがあります。

開始中 ( STARTING )

EMRクラスターが起動中

待機中 ( WAITING )

EMRクラスターがアイドル状態（ステップの実行待ち）

実行中 ( RUNNING )

EMRクラスターがステップを実行中

終了済み ( TERMINATED )

EMRクラスターが停止済み

EMRクラスターの起動 の手順でEMRクラスターが正常に起動し、ステータスが 待機中 ( WAITING ) になっていることを確認して以降の手順に進みます。

EMRクラスターにAsakusa Frameworkをデプロイ

EMRクラスターが起動したら、 デプロイメントアーカイブをS3に配置 でS3に配置したAsakusa FrameworkのデプロイメントアーカイブをEMRクラスターのマスターノードにデプロイします。

EMRクラスターに対して処理を要求するには、コンソールやCLIから「ステップ」と呼ばれる処理単位を登録します。

コンソール

クラスター詳細画面で以下の手順でデプロイを実行します。

画面上部の ステップの追加 ボタンを押下する

ステップの追加 ダイアログで以下の通りに入力し、 追加 ボタンを押下する

ステップタイプ

カスタム JAR を選択

名前

任意のステップ名を入力 (この名前はステップ一覧に表示されます)

JAR の場所

以下のS3パスを入力 2

s3://elasticmapreduce/libs/script-runner/script-runner.jar

引数

以下2つの引数を半角スペース区切りで指定 3

第1引数: s3://asakusafw/emr/deploy-asakusa.sh

第2引数: デプロイメントアーカイブをS3に配置 で配置したデプロイメントアーカイブのS3パス

例: s3://[mybucket]/asakusafw/asakusafw-example-basic-spark.tar.gz

失敗時の動作

次へ を選択

以上の手順でマスターノード上にAsakusa Frameworkのデプロイ処理が実行されます。

正常にデプロイが完了したことを確認するには、クラスター詳細画面の ステップ セクションを展開して、ステップ一覧に表示されるデプロイ用のステップを確認します。

デプロイ用のステップのステータスが 完了 と表示されればデプロイは成功です。

デプロイ用のステップのステータスが 失敗 と表示されデプロイが失敗した場合は、ダイアログの入力内容を確認してください。もしくは、EMRクラスター上のステップのログを確認します。ステップのログの確認方法は後述の アプリケーションの実行結果を確認 を参照してください。

2

script-runner.jar はEMRが提供する、任意のスクリプトをマスターノード上で実行するためのツールです。

3

deploy-asakusa.sh はAsakusa Frameworkが公開しているデプロイ用のスクリプトで、引数に指定したS3パスに配置されているデプロイメントアーカイブを $HOME/asakusa に展開します。

CLI

AWS CLI を使ったデプロイ例を以下に示します。

aws emr add-steps --cluster-id j-XXXXXXXXXXXXX --steps \
Type=CUSTOM_JAR,\
Name=DeployAsakusa,\
ActionOnFailure=CONTINUE,\
Jar=s3://elasticmapreduce/libs/script-runner/script-runner.jar,\
Args=s3://asakusafw/emr/deploy-asakusa.sh,\
s3://[mybucket]/asakusafw/asakusafw-example-basic-spark.tar.gz

ステップを登録すると、以下のようにステップIDが表示されます。ステップIDはステップの実行結果を確認する場合などで使用します。

{
    "StepIds": [
        "s-XXXXXXXXXXXXX"
    ]
}

デプロイの結果を確認します。

aws emr describe-step --cluster-id j-XXXXXXXXXXXXX --step-id s-XXXXXXXXXXXXX \
 --query 'Step.Status.State'

"COMPLETED"

バッチアプリケーションの実行

EMR環境にデプロイしたAsakusa Frameworkのバッチアプリケーションを実行します。

バッチアプリケーションの実行の流れは、以下のようになります。

アプリケーションの入力データをS3に配置

アプリケーションのステップを実行

アプリケーションの実行結果を確認

アプリケーションの出力データをS3から取得

以下、これらの手順について説明します。

アプリケーションの入力データをS3に配置

アプリケーションの入力データをS3に配置します。

入力データを配置するS3上のパスは、 デプロイメント構成の設定 の手順内で build.gradle に設定したDirect I/Oのファイルシステムパス ( directioRootFsPath の値 ) を基点とします。

サンプルアプリケーションの例では、プロジェクトに含まれるテストデータのディレクトリ src/test/example-dataset 配下のファイルをこのディレクトリ構造ごとS3のパスに配置します。

本書の例では、サンプルアプリケーションのテストデータを配置したS3のパスは以下のようになります。

s3://[mybucket]/app-data
 ├── master
 │   └── item_info.csv
 │   └── store_info.csv
 └── sales
     └── 2011-04-01.csv

コンソール

AWSマネジメントコンソールなどを使ってテストデータをアップロードします。先述の デプロイメントアーカイブをS3に配置 などを参考にしてください。

CLI

以下は、AWS CLIによるテストデータのアップロードの例です。

aws s3 cp --recursive src/test/example-dataset s3://[mybucket]/app-data

Attention

上記例を参考にコマンドを入力する際は、必ずアップロード先のS3バケットのパスを実際に使用するパスに置き換えてください。

アプリケーションのステップを実行

ステップを通じてYAESSを実行することでアプリケーションをEMRクラスター上で実行します。

コンソール

クラスター詳細画面で以下の手順でデプロイを実行します。

画面上部の ステップの追加 ボタンを押下する

ステップの追加 ダイアログで以下の通りに入力し、 追加 ボタンを押下する

ステップタイプ

カスタム JAR を選択

名前

任意のステップ名を入力 (この名前はステップ一覧に表示されます)

JAR の場所

以下のS3パスを入力 4

s3://asakusafw/emr/asakusa-script-runner.jar

引数

以下2つの引数を半角スペース区切りで指定 5

第1引数: $ASAKUSA_HOME/yaess/bin/yaess-batch.sh

第2引数以降: yaess-batch.sh の引数

例: spark.example.summarizeSales -A date=2011-04-01

失敗時の動作

次へ を選択

以上の手順でバッチアプリケーションが実行されます。

4

asakusa-script-runner.jar はAsakusa Frameworkが公開しているツールで、 ${ASAKUSA_HOME} 配下の指定したスクリプトを実行します。

5

Arguments に入力するYAESSコマンドは、通常コマンドライン上で yaess-batch.sh を実行する形式と同じです。例えばサンプルアプリケーションの実行では Asakusa Framework スタートガイド - サンプルアプリケーションの実行 の実行例のコマンド記述がそのまま使用できます。

CLI

AWS CLI を使ったバッチアプリケーション実行例を以下に示します。

aws emr add-steps --cluster-id j-XXXXXXXXXXXXX --steps \
Type=CUSTOM_JAR,\
Name=ExampleBatch,\
ActionOnFailure=CONTINUE,\
Jar=s3://asakusafw/emr/asakusa-script-runner.jar,\
Args='[$ASAKUSA_HOME/yaess/bin/yaess-batch.sh,spark.example.summarizeSales,-A,date=2011-04-01]'

Attention

Args の値全体は上の例のように '[ ]' で囲むことを推奨します。こうすることで、 Args の値に key=value 形式や ${...} といった形式が含まれていてもそのまま記述できます。

また、 Args の値に複数の引数を指定する場合は、半角スペースではなくカンマ区切りになることに注意してください。

アプリケーションの実行結果を確認

アプリケーションのステップを実行 で実行したステップの実行結果を確認します。

コンソール

クラスター詳細画面の Steps セクションを展開して、ステップ一覧に表示されるデプロイ用のステップを確認します。

アプリケーションを実行したステップのステータスが 完了 と表示されればアプリケーションの実行は正常に完了しています。

ステップのステータスが 失敗 と表示されアプリケーションが失敗した場合は、ステップのログを確認します。

ステップのログは、ステップ一覧の列 ログファイル 上の ログの表示 を選択します。このログは定期的(およそ5分ごと)にEMRクラスターの各ノードのログが収集されます。ログの収集が終わっていない場合は、間隔をおいてリロードアイコンを押下します。

ログが収集されると、以下のようにログの種類ごとにリンクが表示されます。

デフォルトの設定では、HadoopやSpark上のログは stdout, YAESSのログは stderr からそれぞれ確認できます。

CLI

AWS CLI を使ったステップのステータス確認の例を以下に示します。

aws emr describe-step --cluster-id j-XXXXXXXXXXXXX --step-id s-XXXXXXXXXXXXX \
 --query 'Step.Status.State'

"COMPLETED"

ステップのログは定期的(およそ5分ごと)に収集され、 EMRクラスターの起動 の 起動パラメータ で --log-uri に指定したS3上のパスに配置されます。これを aws s3 コマンド等で取得して確認します。

アプリケーションの出力データをS3から取得

アプリケーションの設定に従ってデータ出力先のS3パスからデータを取得します。

サンプルアプリケーションの例では、入力データと出力データを配置するファイルシステムパスは同じです。デプロイメント構成の設定 の手順内で build.gradle に設定したDirect I/O のファイルシステムパス ( directioRootFsPath の値 ) 配下になります。

本書の例では、サンプルアプリケーションの出力データのS3パスは以下のようになります。

s3://[mybucket]/app-data
 └── result
     ├── category
     │    └── result.csv
     └── error
          └── 2011-04-1.csv

コンソール

AWSマネジメントコンソールなどを使って出力データをダウンロードします。

CLI

AWS CLI を使ったファイルダウンロードの例を以下に示します。

aws s3 cp --recursive s3://[mybucket]/app-data/result /tmp/result

Attention

上記例を参考にコマンドを入力する際は、必ずダウンロード元のS3バケットのパスを実際に使用するパスに置き換えてください。

EMRクラスターの停止

使用が終わったEMRクラスターを停止します。

Warning

EMRクラスターを稼働し続けると、その分課金が発生し続けます。不要になったEMRクラスターは忘れずに停止してください。

コンソール

クラスター詳細画面上部の Terminate ボタンを押下する。

クラスターを終了 ダイアログで 削除 ボタンを押下する

EMRクラスターが完全に停止すると、画面上部のステータスが 削除 と表示されます。

CLI

AWS CLI を使ったEMRクラスター停止の例を以下に示します。

aws emr terminate-clusters --cluster-ids j-XXXXXXXXXXXXX

クラスターが停止したことを確認します。

aws emr describe-cluster --cluster-id j-XXXXXXXXXXXXX \
 --query 'Cluster.Status.State'

"TERMINATED"

Asakusa FrameworkとHiveを連携して利用する

対象バージョン: Asakusa Framework 0.7.0 以降

この文書では、Asakusa Framework と Apache Hive [https://hive.apache.org/] （以下「Hive」）を連携して利用する方法について説明します。

See also

本書で説明するAsakusa FrameworkのHive連携に関する機能の詳細は、 Direct I/O Hive を参照してください。

はじめに

Apache HiveはHadoop上のデータをSQLライクな言語によって操作するためのプロダクトです。

Asakusa Frameworkは複雑なバッチアプリケーションを高品質に開発するための機能セットを中心に提供しています。一方で、データを様々な観点でアドホックに抽出したり、データをインタラクティブに操作するといった用途に対する機能は提供していません。

HiveのようなSQLライクのクエリーを利用した、インタラクティブなデータ操作を提供するプロダクトをAsakusa Frameworkと組み合わせることで、より高度で柔軟なデータ処理システムを実現することができます。

SQL on Hadoop 周辺プロダクトとの連携

本書の内容をベースとして、Hiveのメタデータ管理方法と互換性がある、SQLベースのクエリーエンジンを持つ様々なプロダクトと連携することも可能です。

SQL on Hadoopとも呼ばれるこのようなプロダクトのうち、オープンソースソフトウェアとして提供されているプロダクトの一例を以下に挙げます。

Impala [http://impala.io/]

Presto [http://prestodb.io/]

Apache Drill [http://incubator.apache.org/drill/]

Attention

各プロダクトはそれぞれHiveとの互換性に関する機能が異なり、また同プロダクトのバージョンによっても機能が異なるため、Asakusa Frameworkが提供するHive連携機能との互換性についても対応状況は様々です。詳しくは各プロダクトのドキュメントを参照してください。

Hive環境の構築

以降の説明では、利用するHadoop環境にHiveが導入済みでHiveの各機能が利用できる状態であることを前提とします。運用環境にHiveをセットアップする方法については、各Hadoopディストリビューションのドキュメントなどを参照してください。

なお Jinrikisha [https://docs.asakusafw.com/jinrikisha/ja/html/index.xml] にはHiveが同梱されており、Jinrikishaで構築した開発環境上で本書の手順を確認することもできます。

コンポーネントの関連

Asakusa FrameworkとHiveを連携したシステムにおける各コンポーネントの関連の概要を以下に示します。

バッチアプリケーションの開発Asakusa DSL(DMDL)

Hiveと連携するバッチアプリケーションは、 Direct I/O Hive を利用して開発します。

Direct I/O Hiveが提供するDMDLの拡張によって、入出力データの形式にカラムナフォーマットファイル( ORCFile または Parquet )を指定することができます。

また、DMDLからHiveのテーブルを作成するためのDDLスクリプトを作成することができます。

Hiveテーブルの作成Hive (Execute DDL)

DMDLから生成したHiveテーブル作成用のDDLスクリプトをHiveのコマンドやWeb UIから実行すると、Hiveのメタストア ( Metastore ) にテーブルの情報が登録されます。

HiveメタストアはHiveのテーブル構造やデータの配置場所に関するメタ情報を保持するデータベースで、主にMySQLやPostgreSQLなどのRDBMSが利用されます。

バッチアプリケーションの実行Asakusa Batchapp (Direct I/O)

Direct I/O Hiveを利用するアプリケーションは、HDFSなどのHadoopファイルシステムに対してカラムナフォーマットファイルの読み書きを行います。

クエリーの実行Hive (Execute DML)

Hiveはメタストアの情報に基づいてHadoopファイルシステム上のデータに対してクエリーを実行し結果を出力します。

Asakusa Frameworkとの連携の場合では、バッチアプリケーションが出力したカラムナフォーマットファイルを持つテーブルに対してクエリーを実行します。

また逆に、クエリーによってカラムナフォーマットファイルを持つテーブルデータを生成し、これをバッチアプリケーションが読み込むこともできます。

バッチアプリケーションの開発

Direct I/O Hiveを利用してHiveと連携するためのバッチアプリケーションを開発します。 Direct I/O Hiveの利用方法について、詳しくは Direct I/O Hive を参照してください。ここでは、Hive連携向けのアプリケーション開発時に考慮すべき内容や参考的な情報などを説明します。

カラムナフォーマットの選択

Hiveとの連携に利用するカラムナフォーマットファイルは、そのフォーマットごとに対応しているデータ型やクエリー実行時の性能特性、データ入出力時のパフォーマンスや生成されるデータサイズなどが異なります。

フォーマットごとの性能特性や入出力時のパフォーマンスは、利用する運用環境の構成によってもその影響度合いが異なります。

また、Hive以外のプロダクトを利用する場合は、そのプロダクトごとに対応しているカラムナフォーマットが異なります。

以上のような点を考慮して、利用するカラムナフォーマットを選択してください。

アプリケーションの例

Asakusa Frameworkの サンプルプログラム集 (GitHub) [http://github.com/asakusafw/asakusafw-examples] にDirect I/O Hiveを利用したサンプルアプリケーションを公開しています。

以下はAsakusa Framework バージョン 0.9.0 を使用したDirect I/O Hiveのサンプルアプリケーションです。

https://github.com/asakusafw/asakusafw-examples/tree/0.9.0/example-directio-hive

Hiveテーブルの作成

バッチアプリケーションの入出力に対応するHiveのテーブルを作成します。

Hiveテーブル用DDLの作成

Direct I/O Hiveを利用しているアプリケーションプロジェクトでは、DMDLスクリプトからHiveのDDLを生成する generateHiveDDL タスクを利用することができます。

generateHiveDDL タスクの実行例は以下の通りです。

./gradlew generateHiveDDL --location /user/asakusa/target/testing/directio/tables

--location オプションを指定した場合、生成する CREATE TABLE 文に対して、 LOCATION (テーブルに対応するデータファイルを配置するHadoopファイルシステム上のパス) 句を追加し、さらにその引数として '<指定したパス>/<テーブル名>' が設定されます。 Hiveはここで指定したパスにディレクトリを作成し、配下にテーブルのデータファイルを格納します。

--location の値はDirect I/Oのデータソース定義やジョブフローDSLに定義するベースパスやリソースパターンの値と対応している必要があります。

例えば、上例の --location に対応するエクスポート定義は以下のようになります。

public class CategorySummaryToOrc extends AbstractCategorySummaryOrcFileOutputDescription {

    @Override
    public String getBasePath() {
        return "tables/category_summary";
    }

    @Override
    public String getResourcePattern() {
        return "*";
    }

Attention

--location オプションには絶対パスまたはスキーマ付きのURIを指定する必要があります。上記は、Direct I/Oのデータストアが /user/asakusa/target/testing/directio を基点とした前提の例です。

Hint

多くの場合、Direct I/Oのベースパス ( getBasePath() ) には --location オプションで指定したディレクトリと重なるように指定するのがよいでしょう。

generateHiveDDL タスクを実行すると、アプリケーションプロジェクトの build/hive-ddl ディレクトリ配下に <プロジェクト名>.sql という名前でHiveのDDL文を含むSQLファイルが生成されます。

See also

generateHiveDDL タスクについてより詳しくは、 Asakusa Gradle Plugin ユーザーガイド - Hive用DDLファイルの生成 を参照してください。

Hiveテーブルの登録

Hiveテーブル登録用のDDLファイルを作成したら、これをHiveから実行してHiveメタストアにテーブル定義を登録します。

ここでは、Hiveのコマンドラインインターフェース(CLI)を使用してDDLファイルを実行する例を示します。 Hiveが導入されてる環境上にDDLファイルを配置し、コマンドラインから hive コマンドを以下のように実行します。

hive -f /tmp/hive-ddl/example-directio-hive.sql

OK
Time taken: 2.577 seconds
OK
Time taken: 0.058 seconds
...

テーブルが正常に登録されていることを確認します。まず hive コマンドをインタラクティブモードで実行します。

hive

show tables クエリーを実行してメタストアに登録したテーブル一覧を表示します。

hive> show tables;

OK
category_summary
error_record
item_info
sales_detail
store_info
Time taken: 0.453 seconds, Fetched: 5 row(s)

See also

HiveのCLIについて詳しくは、Hiveのドキュメント LanguageManual Cli [https://cwiki.apache.org/confluence/display/Hive/LanguageManual+Cli] などを参照してください。

バッチアプリケーションの実行

Direct I/O Hiveを利用したバッチアプリケーションを実行します。

運用環境に対してAsakusa Frameworkとバッチアプリケーションをデプロイして実行する方法については、 Asakusa Framework デプロイメントガイド を参照してください。

先述の アプリケーションの例 で紹介したサンプルアプリケーションを実行する場合は、以下のようにサンプルデータを配置してYAESSコマンドを実行します。

Warning

以下の例を実行すると、 target/testing/directio/tables 以下のファイルをすべて削除します。削除する前に重要なファイルがこのパスに存在しないかを必ず確認してください。

hadoop fs -rm -r target/testing/directio/tables
hadoop fs -put /tmp/example-dataset/tables target/testing/directio/tables

$ASAKUSA_HOME/yaess/bin/yaess-batch.sh example.summarizeSales

クエリーの実行

バッチアプリケーションが生成したテーブルデータは直接Hiveのクエリーで参照することができます。

以下は、サンプルアプリケーションの実行結果データを参照する例です。

hive> select * from category_summary;
OK
1300    12  1596
1401    15  1470
1600    28  5400

hive> select * from error_record;
OK
1990-01-01 10:40:00 0001    9999999999999   商品不明
2011-04-01 11:00:00 0001    9999999999999   商品不明
2011-04-01 20:00:00 9999    4922010001000   店舗不明

ユーティリティツールユーザーガイド

この文書では、Asakusa Frameworkが提供するコマンドラインツールの利用方法について解説します。このコマンドラインツール群を利用することで、運用環境上のメンテナンス作業を軽減します。

ユーティリティツールの配置

すべてのユーティリティツールは、Asakusa Frameworkをインストールしたパスの $ASAKUSA_HOME/tools/bin ディレクトリ内に格納されています。

ユーティリティツールのコマンド一覧を以下に示します。

ユーティリティツール コマンド一覧

サブコマンド

説明

directio

Direct I/O CLI 1

directio.cmd

Direct I/O CLI のWindows向けコマンド

setup.jar

デプロイメントアーカイブのセットアップ

hadoop-fs-clean.sh

Hadoopファイルシステムのクリーニング

1

Direct I/O CLI については Direct I/O CLI ユーザーガイド を参照してください。

セットアップに関するユーティリティ

デプロイメントアーカイブのセットアップ

setup.jar はAsakusa Frameworkのデプロイメントアーカイブを展開後に実行することで展開したファイルに対して適切な実行権限を付与するなどの処理を行い、バッチアプリケーションを実行可能な状態にセットアップします。

利用方法の例は、 Asakusa Framework スタートガイド や Asakusa Framework デプロイメントガイド を参照してください。

書式

java -jar $ASAKUSA_HOME/tools/bin/setup.jar [/path/to/installation] [--help]

setup.jar は java コマンドを経由して実行します。オプションを指定せず実行した場合、 環境変数 $ASAKUSA_HOME 配下に配置されているファイルに対してセットアップ処理を行います。オプションにディレクトリパスを指定すると、そのディレクトリ配下に配置されているファイルに対してセットアップ処理を行います。

使用例

mkdir -p "$ASAKUSA_HOME"
cd "$ASAKUSA_HOME"
tar -xzf /tmp/asakusafw-example-basic-m3bp.tar.gz
java -jar $ASAKUSA_HOME/tools/bin/setup.jar

Hadoopに関するユーティリティ

Hadoopに関するユーティリティツールは、 $ASAKUSA_HOME/tools/bin ディレクトリ内の hadoop- から始まるスクリプトとして提供しています。

いずれのツールも hadoop コマンドを経由して実行するため、環境にHadoopがインストールされている必要があります。また、Hadoopのインストール先を通知するために、以下の環境変数のいずれかが必要です。

HADOOP_CMD

hadoop コマンドのパス

HADOOP_HOME

Hadoopのインストール先

PATH

hadoop コマンドが通っているパス

環境変数の設定方法は、 コマンドラインツール全体の設定 を参照してください。

Hadoopファイルシステムのクリーニング

$ASAKUSA_HOME/tools/bin/hadoop-fs-clean.sh コマンドを利用すると、Hadoopファイルシステム上の古いファイルやディレクトリを一括して削除できます。

以下の形式で指定します。

hadoop-fs-clean.sh -k <days> [-r] [-s] <path> [<path> [...]]

コマンドに指定可能な引数は以下のとおりです。

-h, -help

ヘルプメッセージを表示して終了します。

-k <days>, -keep-days <days> (必須)

最終更新から <days> 日以上経過したファイルのみを削除します。 0 を指定した場合には現在時刻よりも古いファイルをすべて削除します。

-r, -recursive

ディレクトリとその内容を再帰的にクリーニングの対象とします。クリーニングによってディレクトリの中身が空になった場合、ディレクトリも削除の対象になります。

-s, -dry-run

クリーニング時にファイルやディレクトリの削除を行わず、ログだけを出力します。

path (必須)

クリーニング対象のパスをURI形式で指定します。 2つ以上のパスを指定することもできます。

* を含むパスなど、 hadoop fs コマンドで有効なパス式を指定できます。

なお、 コマンド引数に -- を指定すると以降の引数をすべて <path> とみなします。対象のURIが - から始まる場合などに有効です。

以下は利用例です。

# HDFS上の /user/asakusa/var/logs ディレクトリ直下のうち、1日経過したファイルを削除する
hadoop-fs-clean.sh -k 1 hdfs://localhost:8020/user/asakusa/var/logs/*

# HDFS上の /user/asakusa/var/logs ディレクトリ内の、10日経過したファイルやディレクトリを再帰的に削除する
hadoop-fs-clean.sh -k 10 hdfs://localhost:8020/user/asakusa/var/logs/* -r

# ローカルファイルシステム上の /tmp/hadoop-asakusa ディレクトリに対する全削除をシミュレーションする
hadoop-fs-clean.sh -dry-run -k 0 file:///tmp/hadoop-asakusa -r

コマンドラインツール全体の設定

上記で紹介したコマンドラインツールは、実行前に $ASAKUSA_HOME/tools/env.sh を読み込んで必要な環境変数の設定などを行います。

以下は同ファイルの内容を改変し、環境変数 HADOOP_CMD を設定する例です。

export HADOOP_CMD=/usr/bin/hadoop

コマンドラインツールのログ設定

上記で紹介したコマンドラインツールは、Hadoopが持つLog4Jのルートロガーに対して出力を行います。

多くのHadoopディストリビューションでは、デフォルトではLog4Jのルートロガーは標準エラー出力に対してログ出力を行うようになっています。

Asakusa on Spark

Asakusa on Sparkは、Asakusa DSLを始めとするAsakusa Frameworkの開発基盤を利用して作成したバッチアプリケーションに対して、Sparkをその実行基盤として利用するための機能セットを提供します。

Asakusa on Sparkの概要と利用方法は、 Asakusa on Spark ユーザガイド を参照してください。

ドキュメント

Asakusa on Spark ユーザガイド

Asakusa on Sparkの最適化設定

Asakusa on Spark リファレンス

Asakusa on Spark Iterative Extensions

リリースノート

過去のリリースノート

Changelogs

リソース

ソースリポジトリ

asakusafw-compiler (GitHub) [https://github.com/asakusafw/asakusafw-compiler]

asakusafw-spark (GitHub) [https://github.com/asakusafw/asakusafw-spark]

APIリファレンス

Asakusa on Spark Gradle Plugins (Groovydoc) [https://docs.asakusafw.com/asakusa-on-spark/0.5.3/release/gradle-plugins/index.html]

リンク

Apache Spark [https://spark.apache.org/]

Asakusa on Spark ユーザガイド

この文書では、 Asakusa Framework [https://docs.asakusafw.com/latest/release/ja/html/index.html] を使って作成したバッチアプリケーションを Apache Spark [http://spark.apache.org/] 上で実行する方法について説明します。

概要

Asakusa on Sparkは、Asakusa DSLを始めとするAsakusa Frameworkの開発基盤を利用して作成したバッチアプリケーションに対して、Sparkをその実行基盤として利用するための機能セットを提供します。

Sparkは高速で汎用性の高い、スケーラブルなデータ処理基盤を提供する目的で作成されたオープンソースソフトウェアです。いくつかの適用用途においてHadoop MapReduceよりも高速に動作する事例が公開されており、現在急速にその利用が拡大しています。

Asakusa Frameworkの適用領域においても、いくつかのケースでSparkを利用することで従来より高速にバッチアプリケーションが動作することを確認しています。Asakusa on Sparkによって、Asakusa Frameworkがより高速で汎用的なバッチアプリケーションの開発/実行基盤として利用できるようになることを目指しています。

構成

Asakusa on Sparkを利用する場合、従来のAsakusa Frameworkが提供するDSLやテスト機構をそのまま利用して開発を行います。アプリケーションをビルドして運用環境向けの実行モジュール（デプロイメントアーカイブ）を作成する段階ではじめてSpark用のコンパイラを利用します。

また、Asakusa DSL Compiler for Sparkで生成したバッチアプリケーションは、従来と同様にYAESSを利用して実行できます。

Asakusa DSL

従来のAsakusa DSLやDMDLで記述したバッチアプリケーションは基本的に変更なしで、Asakusa DSL Compiler for Sparkを利用してSpark向けの実行モジュールを生成することができます。

テスト機構

従来のAsakusa DSLのテスト方法と同様に、テストドライバーを利用してAsakusa DSLのテストを実行することができます。このとき、Sparkは特に利用しません。

アプリケーションの実行

従来と同様、YAESSを利用してバッチアプリケーションを実行することができます。

外部システム連携

Direct I/OやWindGateといった外部システム連携モジュールはSpark向けのバッチアプリケーションでもそのまま利用することができます。

Attention

Direct I/OやWindGateでHadoopの機能を利用するよう設定した場合は、Hadoopが動作する環境が併せて必要になります。

対応プラットフォーム

Spark

本バージョンのAsakusa on Sparkは、Spark 2.3.2 で動作を検証しています。

Attention

本バージョンのAsakusa on Sparkは、 Spark 1.6.x 以前のバージョンでは動作しません。

Hadoopディストリビューション

Asakusa on Sparkが動作を検証しているHadoopディストリビューションは、対応プラットフォーム の「Hadoopディストリビューション」を参照してください。

開発環境の構築

新規に開発環境を構築する場合は、以下のドキュメントなどを参考にして開発環境を準備してください。

Asakusa Framework スタートガイド

Asakusa Framework チュートリアル [https://docs.asakusafw.com/basic-tutorial/0.10/release/ja/html/index.html]

アプリケーションの開発

開発環境上で Asakusa Frameworkのバッチアプリケーションを開発し、Spark向けのアプリケーションをビルドする方法を見ていきます。

プロジェクトテンプレート

Asakusa on Sparkを利用する構成を持つアプリケーション開発用のプロジェクトテンプレートは、以下リンクからダウンロードします。

asakusa-spark-template-0.10.3.tar.gz [http://www.asakusafw.com/download/gradle-plugin/asakusa-spark-template-0.10.3.tar.gz]

See also

プロジェクトテンプレートの構成や利用方法については、 Asakusa Gradle Plugin ユーザーガイド を参照してください。

サンプルアプリケーション

サンプルプログラム集 (GitHub) [http://github.com/asakusafw/asakusafw-examples] に含まれるプロジェクト example-basic-spark はAsakusa on Sparkを利用する基本的なサンプルアプリケーションプロジェクトです。

このプロジェクトはAsakusa on Spark用のプロジェクトテンプレートに対して、 Asakusa Framework スタートガイド などで説明しているサンプルアプリケーション「カテゴリー別売上金額集計バッチ」用のソースコードが追加されています。

Asakusa on Spark Gradle Plugin

Asakusa on Spark Gradle Pluginは、アプリケーションプロジェクトに対してAsakusa on Sparkのさまざまな機能を追加します。

プロジェクトテンプレート や サンプルアプリケーション で紹介したプロジェクトには、Asakusa on Spark Gradle Pluginがあらかじめ利用可能になっています。

その他のプロジェクトで Asakusa on Spark Gradle Pluginを有効にするには、アプリケーションプロジェクトのビルドスクリプト ( build.gradle )に対して以下の設定を追加します。

apply plugin: 'asakusafw-spark'

以下はAsakusa on Spark Gradle Pluginの設定を持つビルドスクリプトの例です。

build.gradle

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.3'
    }
}

apply plugin: 'asakusafw-sdk'
apply plugin: 'asakusafw-organizer'
apply plugin: 'asakusafw-spark'
apply plugin: 'eclipse'

See also

Asakusa on Spark Gradle Pluginのより詳細な情報は、 Asakusa Gradle Plugin リファレンス や Asakusa on Spark リファレンス などを参照してください。

アプリケーションのビルド

Asakusa on Spark Gradle Plugin を設定した状態で、Gradleタスク sparkCompileBatchapps を実行すると、Asakusa DSL Compiler for Sparkを利用し、Spark向けのバッチアプリケーションのビルドを実行します。

./gradlew sparkCompileBatchapps

sparkCompileBatchapps タスクを実行すると、アプリケーションプロジェクトの build/spark-batchapps 配下にビルド済みのバッチアプリケーションが生成されます。

標準の設定では、Asakusa DSL Compiler for Sparkよって生成したバッチアプリケーションは接頭辞に spark. が付与されます。例えば、サンプルアプリケーションのバッチID example.summarizeSales の場合、Spark向けのバッチアプリケーションのバッチIDは spark.example.summarizeSales となります。

See also

Asakusa DSL Compiler for Sparkで利用可能な設定の詳細は、 Asakusa on Spark リファレンス を参照してください。

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

Asakusa on Spark Gradle Plugin を設定した状態で、Asakusa Frameworkのデプロイメントアーカイブを作成すると、Hadoop MapReduce用とSpark用のバッチアプリケーションアーカイブを含むデプロイメントアーカイブを生成します。

デプロイメントアーカイブを生成するには Gradleの assemble タスクを実行します。

./gradlew assemble

Hint

Shafuを利用する場合は、プロジェクトを選択してコンテキストメニューから Jinrikisha (人力車) ‣ Asakusaデプロイメントアーカイブを生成 を選択します。

アプリケーションの実行

ここでは、Asakusa on Spark固有の実行環境の設定について説明します。

Asakusa Frameworkの実行環境の構築方法やバッチアプリケーションを実行する方法の基本的な流れは、 Asakusa Framework デプロイメントガイド などを参照してください。

Sparkのセットアップ

以降の説明で実施する手順は、Sparkがセットアップ済みのHadoopクラスターを対象とします。SparkのセットアップについてはSparkのドキュメントや利用するHadoopディストリビューションのドキュメント等を参考にして下さい。

実行コマンドの設定

Sparkを起動する際には、起動する対象の spark-submit コマンドの配置場所を環境変数に指定する必要があります。 Spark向けのバッチアプリケーションを実行する際には、次の手順で spark-submit コマンドを検索します。

環境変数 SPARK_CMD が設定されている場合、 $SPARK_CMD を spark-submit コマンドとみなして利用します。

spark-submit コマンドのパス ( 環境変数 PATH ) が通っている場合、それを利用します。

上記の手順で spark-submit コマンドが見つからない場合、対象処理の実行に失敗します。

Asakusa on Sparkの実行に環境変数を利用する場合、 $ASAKUSA_HOME/spark/conf/env.sh 内でエクスポートして定義できます。

export SPARK_CMD=/opt/spark/bin/spark-submit

Tip

バッチアプリケーション実行時の環境変数は、YAESSプロファイルで設定することも可能です。

Asakusa on Sparkを利用する場合、コマンドラインジョブのプロファイル command.spark が利用できます。 $ASAKUSA_HOME/yaess/conf/yaess.properties に command.spark.env.SPARK_CMD といったような設定を追加することで、YAESSからSparkを実行する際に環境変数が設定されます。

YAESSのコマンドラインジョブの設定方法について詳しくは、 YAESSユーザーガイド - コマンドラインジョブの実行 などを参照してください。

spark-submit コマンドに対するオプション引数は、環境変数 ASAKUSA_SPARK_OPTS で指定できます。

以下は ASAKUSA_SPARK_OPTS の設定例です。

export ASAKUSA_SPARK_OPTS="--master yarn --deploy-mode cluster"

環境変数 SPARK_CMD_LAUNCHER は実行コマンドの先頭に任意のコマンド文字列を追加します。

バッチアプリケーションの実行

デプロイしたバッチアプリケーションをYAESSを使って実行します。

$ASAKUSA_HOME/yaess/bin/yaess-batch.sh コマンドに実行するバッチIDとバッチ引数を指定してバッチを実行します。標準の設定では、Spark向けのバッチアプリケーションはバッチIDの接頭辞に spark. が付与されているので、このバッチIDを指定します。

Attention

標準の設定では、バッチIDの接頭辞に spark. がついていないバッチIDは従来のHadoop MapReduce向けバッチアプリケーションです。YAESSの実行時にバッチIDの指定を間違えないよう注意してください。

例えば、サンプルアプリケーションを実行する場合は、以下のように yaess-batch.sh を実行します。

$ASAKUSA_HOME/yaess/bin/yaess-batch.sh spark.example.summarizeSales -A date=2011-04-01

See also

サンプルアプリケーションのデプロイやデータの配置、実行結果の確認方法などは、 Asakusa Framework スタートガイド - サンプルアプリケーションの実行 を参照してください。

バッチアプリケーション実行時の設定

$ASAKUSA_HOME/spark/conf/spark.properties にはバッチアプリケーション実行時の設定を定義します。実行環境に応じて以下の値を設定してください｡

com.asakusafw.spark.parallelism

バッチアプリケーション実行時に、ステージごとの標準的なタスク分割数を指定します。

ステージの特性（推定データサイズや処理内容）によって、この分割数を元に実際のタスク分割数が決定されます。

標準的には、SparkのExecutorに割り当てた全コア数の1〜4倍程度を指定します。

このプロパティが設定されていない場合、 spark.default.parallelism の値を代わりに利用します。いずれのプロパティも設定されていない場合、下記の既定値を利用します。

既定値: 2

See also

その他のバッチアプリケーション実行時の設定については、 Asakusa on Sparkの最適化設定 を参照してください。

Asakusa on Sparkの最適化設定

この文書では、Asakusa on Sparkのバッチアプリケーション実行時の最適化設定について説明します。

設定方法

Asakusa on Sparkのバッチアプリケーション実行時の設定は、 設定ファイル を使う方法と 環境変数 を使う方法があります。

設定ファイル

Asakusa on Sparkに関するバッチアプリケーション実行時のパラメータは、 $ASAKUSA_HOME/spark/conf/spark.properties に記述します。このファイルは、Asakusa on Spark Gradle Pluginを有効にしてデプロイメントアーカイブを作成した場合にのみ含まれています。

このファイルに設定した内容はSpark向けのバッチアプリケーションの設定として使用され、バッチアプリケーション実行時の動作に影響を与えます。

設定ファイルはJavaのプロパティファイルのフォーマットと同様です。以下は spark.properties の設定例です。

spark.properties

## the number of parallel tasks of each Asakusa stage
com.asakusafw.spark.parallelism=40

## the number of records of the in-memory buffer for each output fragment
com.asakusafw.spark.fragment.bufferSize=256

環境変数

Asakusa on Sparkに関するバッチアプリケーション実行時のパラメータは、環境変数 ASAKUSA_SPARK_ARGS に設定することもできます。

環境変数 ASAKUSA_SPARK_ARGS の値には --engine-conf <key>=<value> という形式でパラメータを設定します。

以下は環境変数の設定例です。

ASAKUSA_SPARK_ARGS='--engine-conf com.asakusafw.spark.parallelism=40 --engine-conf com.asakusafw.spark.fragment.bufferSize=256'

設定ファイルと環境変数で同じプロパティが設定されていた場合、環境変数の値が利用されます。

Hint

環境変数による設定は、バッチアプリケーションごとに設定を変更したい場合に便利です。

Attention

yaess-batch.sh などのYAESSコマンドを実行する環境と、Sparkを実行する環境が異なる場合（例えばYAESSのSSH機能を利用している場合）に、 YAESSコマンドを実行する環境の環境変数がSparkを実行する環境に受け渡されないことがある点に注意してください。

YAESSではYAESSコマンドを実行する環境の環境変数をYAESSのジョブ実行先に受け渡すための機能がいくつか用意されているので、それらの機能を利用することを推奨します。詳しくは YAESSユーザーガイド などを参照してください。

設定項目

Asakusa on Sparkのバッチアプリケーション実行時の設定項目は以下の通りです。

com.asakusafw.spark.parallelism

バッチアプリケーション実行時に、ステージごとの標準的なタスク分割数を指定します。

ステージの特性（推定データサイズや処理内容）によって、この分割数を元に実際のタスク分割数が決定されます。

標準的には、SparkのExecutorに割り当てた全コア数の1〜4倍程度を指定します。

このプロパティが設定されていない場合、 spark.default.parallelism の値を代わりに利用します。いずれのプロパティも設定されていない場合、下記の既定値を利用します。

既定値: 2

com.asakusafw.spark.parallelism.scale.small

コンパイラが「比較的小さなデータ」と判断したステージのタスク分割数を標準からの割合で指定します。

標準のタスク分割数については com.asakusafw.spark.parallelism で設定できます。また、データサイズの閾値についてはコンパイラプロパティの spark.parallelism.limit.small で設定できます。

既定値: 0.5

com.asakusafw.spark.parallelism.scale.large

コンパイラが「比較的大きなデータ」と判断したステージのタスク分割数を標準からの割合で指定します。

標準のタスク分割数については com.asakusafw.spark.parallelism で設定できます。また、データサイズの閾値についてはコンパイラプロパティの spark.parallelism.limit.large で設定できます。

既定値: 2.0

com.asakusafw.spark.parallelism.scale.huge

コンパイラが「巨大なデータ」と判断したステージのタスク分割数を標準からの割合で指定します。

標準のタスク分割数については com.asakusafw.spark.parallelism で設定できます。また、データサイズの閾値についてはコンパイラプロパティの spark.parallelism.limit.huge で設定できます。

既定値: 4.0

See also

コンパイラプロパティについては、 Asakusa on Spark リファレンス を参照してください。

com.asakusafw.spark.fragment.bufferSize

バッチアプリケーション実行時に、各演算子の出力となるデータモデルオブジェクトをメモリ上に保持する個数を指定します。グループ単位で実行される演算子に対しては、グループ単位での保持数になります。

演算子の処理中に出力されるデータモデルオブジェクトの個数がこのプロパティに設定した値を超えた時点で、メモリ上に保持していたデータモデルオブジェクトの内容をファイル上のバッファに退避します。

このプロパティを設定しない、または負の値を指定した場合、演算子の処理が終了するまで出力対象となるすべてのデータモデルオブジェクトはメモリ上に保持されます。

既定値: -1

Hint

ある演算子の出力サイズが大きくメモリ不足エラーが発生するような場合に、このプロパティを設定することで問題を回避できる可能性があります。

Attention

ファイル上のバッファは利用するJVMのシステムプロパティ java.io.tmpdir で設定されているディレクトリ配下に作成されます。大量のバッファが出力されるような処理を実行する場合には、出力先に十分な空き領域を確保する必要があることに注意してください。

spark.hadoop.com.asakusafw.bridge.directio.input.combine

Direct I/O によるファイルの読み込み時に、ここで指定した数値を上限として、Direct I/Oの入力ごとに入力スプリットを結合します。

Asakusa on Sparkでは入力ファイルの数に応じてSparkタスクを生成して実行しますが、入力ファイル数が膨大であるような場合、非常に多くのSparkタスクが生成されることでパフォーマンスが劣化したり、実行環境が不安定になる現象が確認されています。そのような場合、このオプションを設定することで上記の問題を回避できる可能性があります。

このオプションはコンパイラプロパティ spark.input.direct に true を指定してコンパイルされたバッチアプリケーションにのみ有効です。

既定値: -1 (無効)

Asakusa on Spark リファレンス

この文書では、Asakusa on Sparkが提供するGradle PluginやDSLコンパイラの設定、およびバッチアプリケーション実行時の設定などについて説明します。

Asakusa on Spark Gradle Plugin リファレンス

Asakusa on Spark Gradle Pluginが提供する機能とインターフェースについて個々に解説します。

プラグイン

asakusafw-spark

アプリケーションプロジェクトで、Asakusa on Sparkのさまざまな機能を有効にする 1 。

このプラグインは asakusafw-sdk プラグインや asakusafw-organizer プラグインを拡張するように作られているため、それぞれのプラグインも併せて有効にする必要がある（ apply plugin: 'asakusafw-spark' だけではほとんどの機能を利用できません）。

1

com.asakusafw.spark.gradle.plugins.AsakusafwSparkPlugin [https://docs.asakusafw.com/asakusa-on-spark/0.5.3/release/gradle-plugins/com/asakusafw/spark/gradle/plugins/AsakusafwSparkPlugin.html]

タスク

sparkCompileBatchapps

Asakusa DSL Compiler for Sparkを利用してDSLをコンパイルする 2 。

asakusafw-sdk プラグインが有効である場合にのみ利用可能。

attachComponentSpark

デプロイメントアーカイブにSpark向けのバッチアプリケーションを実行するためのコンポーネントを追加する。

asakusafw-organizer プラグインが有効である場合にのみ利用可能。

asakusafwOrganizer.spark.enabled に true が指定されている場合、自動的に有効になる。

attachSparkBatchapps

デプロイメントアーカイブに sparkCompileBatchapps でコンパイルした結果を含める。

asakusafw-sdk , asakusafw-organizer の両プラグインがいずれも有効である場合にのみ利用可能。

asakusafwOrganizer.batchapps.enabled に true が指定されている場合、自動的に有効になる。

2

com.asakusafw.gradle.tasks.AsakusaCompileTask [https://docs.asakusafw.com/0.10.3/release/gradle-plugins/com/asakusafw/gradle/tasks/AsakusaCompileTask.html]

タスク拡張

assemble

デプロイメントアーカイブを生成する。

asakusafw-spark と asakusafw-organizer プラグインがいずれも有効である場合、 sparkCompileBatchapps が依存関係に追加される。

compileBatchapp

Asakusa DSLコンパイラを使ってバッチアプリケーションのコンパイルを行い、実行可能モジュールを生成する。

asakusafw-spark プラグインが有効である場合、 sparkCompileBatchapps が依存関係に追加される。

jarBatchapp

compileBatchapp タスクで生成したバッチアプリケーションを含むjarファイルを生成する。

asakusafw-spark プラグインが有効である場合、 sparkCompileBatchapps タスクの生成物がjarファイルの内容に追加される。

規約プロパティ拡張

Batch Application Plugin ( asakusafw ) への拡張

Asakusa on Spark Gradle Pluginは Batch Application Plugin に対して Asakusa on Sparkのビルド設定を行うための規約プロパティを追加します。この規約プロパティは、 asakusafw ブロック内の参照名 spark でアクセスできます 3 。

以下、 build.gradle の設定例です。

build.gradle

asakusafw {
    spark {
        include 'com.example.batch.*'
        option 'operator.logging.level', 'warn'
    }

この規約オブジェクトは以下のプロパティを持ちます。

spark.version

Asakusa on Sparkのコンポーネントバージョンを保持する。

この値は設定による変更は不可。

既定値: Asakusa on Spark Gradle Pluginが保持する既定のバージョン

spark.outputDirectory

コンパイラの出力先を指定する。

文字列や java.io.File などで指定し、相対パスが指定された場合にはプロジェクトからの相対パスとして取り扱う。

既定値: "$buildDir/spark-batchapps"

spark.include

コンパイルの対象に含めるバッチクラス名のパターンを指定する。

バッチクラス名には * でワイルドカードを含めることが可能。

また、バッチクラス名のリストを指定した場合、それらのパターンのいずれかにマッチしたバッチクラスのみをコンパイルの対象に含める。

既定値: null (すべて)

spark.exclude

コンパイルの対象から除外するバッチクラス名のパターンを指定する。

バッチクラス名には * でワイルドカードを含めることが可能。

また、バッチクラス名のリストを指定した場合、それらのパターンのいずれかにマッチしたバッチクラスをコンパイルの対象から除外する。

include と exclude がいずれも指定された場合、 exclude のパターンを優先して取り扱う。

既定値: null (除外しない)

spark.runtimeWorkingDirectory

実行時のテンポラリワーキングディレクトリのパスを指定する。

パスにはURIやカレントワーキングディレクトリからの相対パスを指定可能。

未指定の場合、コンパイラの標準設定である「 target/hadoopwork 」を利用する。

既定値: null (コンパイラの標準設定を利用する)

spark.option

コンパイラプロパティ （コンパイラのオプション設定）を追加する。

後述する コンパイラプロパティ を <key>, <value> の形式で指定する 4 。

既定値: (Spark向けのコンパイルに必要な最低限のもの)

spark.batchIdPrefix

Spark向けのバッチアプリケーションに付与するバッチIDの接頭辞を指定する。

文字列を設定すると、それぞれのバッチアプリケーションは「 <接頭辞><本来のバッチID> 」というバッチIDに強制的に変更される。

空文字や null を指定した場合、本来のバッチIDをそのまま利用するが、他のコンパイラが生成したバッチアプリケーションと同じバッチIDのバッチアプリケーションを生成した場合、アプリケーションが正しく動作しなくなる。

既定値: "spark."

spark.failOnError

Spark向けのコンパイルを行う際に、コンパイルエラーが発生したら即座にコンパイルを停止するかどうかを選択する。

コンパイルエラーが発生した際に、 true を指定した場合にはコンパイルをすぐに停止し、 false を指定した場合には最後までコンパイルを実施する。

既定値: true (即座にコンパイルを停止する)

3

これらのプロパティは規約オブジェクト com.asakusafw.gradle.plugins.AsakusafwCompilerExtension [https://docs.asakusafw.com/0.10.3/release/gradle-plugins/com/asakusafw/gradle/plugins/AsakusafwCompilerExtension.html] が提供します。

4

コンパイラプロパティを指定する方法は他にいくつかの方法があります。詳しくは com.asakusafw.gradle.plugins.AsakusafwCompilerExtension [https://docs.asakusafw.com/0.10.3/release/gradle-plugins/com/asakusafw/gradle/plugins/AsakusafwCompilerExtension.html] のメソッドの説明を参照してください。

Framework Organizer Plugin ( asakusafwOrganizer ) への拡張

Asakusa on Spark Gradle Plugin は Framework Organizer Plugin に対して Asakusa on Sparkのビルド設定を行うための規約プロパティを追加します。この規約プロパティは、 asakusafwOrganizer ブロック内の参照名 spark でアクセスできます 5 。

この規約オブジェクトは以下のプロパティを持ちます。

spark.enabled

デプロイメントアーカイブにSpark向けのバッチアプリケーションを実行するためのコンポーネントを追加するかどうかを指定する (各プロファイルのデフォルト値)。

true を指定した場合にはコンポーネントを追加し、 false を指定した場合には追加しない。

既定値: true (コンポーネントを追加する)

<profile>.spark.enabled

対象のプロファイルに対し、デプロイメントアーカイブにSpark向けのバッチアプリケーションを実行するためのコンポーネントを追加するかどうかを指定する。

前述の spark.enabled と同様だが、こちらはプロファイルごとに指定できる。

既定値: asakusafwOrganizer.spark.enabled (全体のデフォルト値を利用する)

5

これらのプロパティは規約オブジェクト com.asakusafw.spark.gradle.plugins.AsakusafwOrganizerSparkExtension [https://docs.asakusafw.com/asakusa-on-spark/0.5.3/release/gradle-plugins/com/asakusafw/spark/gradle/plugins/AsakusafwOrganizerSparkExtension.html] が提供します。

コマンドラインオプション

sparkCompileBatchapps タスクを指定して gradlew コマンドを実行する際に、 sparkCompileBatchapps --update <バッチクラス名> と指定することで、指定したバッチクラス名のみをバッチコンパイルすることができます。

また、バッチクラス名の文字列には * をワイルドカードとして使用することもできます。

以下の例では、パッケージ名に com.example.target.batch を含むバッチクラスのみをバッチコンパイルしてデプロイメントアーカイブを作成しています。

./gradlew sparkCompileBatchapps --update com.example.target.batch.* assemble

そのほか、 sparkCompileBatchapps タスクは gradlew コマンド実行時に以下のコマンドライン引数を指定することができます。

--options <k1=v1[,k2=v2[,...]]>

追加のコンパイラプロパティを指定する。

規約プロパティ asakusafw.spark.option で設定したものと同じキーを指定した場合、それらを上書きする。

--batch-id-prefix <prefix.>

生成するバッチアプリケーションに、指定のバッチID接頭辞を付与する。

規約プロパティ asakusafw.spark.batchIdPrefix の設定を上書きする。

--fail-on-error <"true"|"false">

コンパイルエラー発生時に即座にコンパイル処理を停止するかどうか。

規約プロパティ asakusafw.spark.failOnError の設定を上書きする。

--update <batch-class-name-pattern>

指定のバッチクラスだけをコンパイルする (指定したもの以外はそのまま残る)。

規約プロパティ asakusafw.spark.{in,ex}clude と同様にワイルドカードを利用可能。

このオプションが設定された場合、規約プロパティ asakusafw.spark.{in,ex}clude の設定は無視する。

Asakusa DSL Compiler for Spark リファレンス

コンパイラプロパティ

Asakusa DSL Compiler for Sparkで利用可能なコンパイラプロパティについて説明します。これらの設定方法については、 Batch Application Plugin ( asakusafw ) への拡張 の spark.option の項を参照してください。

directio.input.filter.enabled

Direct I/O input filterを有効にするかどうか。

true ならば有効にし、 false ならば無効にする。

既定値: true

operator.checkpoint.remove

DSLで指定した @Checkpoint 演算子をすべて除去するかどうか。

true ならば除去し、 false ならば除去しない。

既定値: false

operator.logging.level

DSLで指定した @Logging 演算子のうち、どのレベル以上を表示するか。

debug , info , warn , error のいずれかを指定する。

既定値: info

operator.aggregation.default

DSLで指定した @Summarize , @Fold 演算子の partialAggregate に PartialAggregation.DEFAULT が指定された場合に、どのように集約を行うか。

total であれば部分集約を許さず、 partial であれば部分集約を行う。

既定値: total

input.estimator.tiny

インポーター記述の getDataSize() に DataSize.TINY が指定された際、それを何バイトのデータとして見積もるか。

値にはバイト数か、 +Inf (無限大)、 NaN (不明) のいずれかを指定する。

主に、 @MasterJoin 系の演算子でJOINのアルゴリズムを決める際など、データサイズによる最適化の情報として利用される。

既定値: 10485760 (10MB)

input.estimator.small

インポーター記述の getDataSize() に DataSize.SMALL が指定された際、それを何バイトのデータとして見積もるか。

その他については input.estimator.tiny と同様。

既定値: 209715200 (200MB)

input.estimator.large

インポーター記述の getDataSize() に DataSize.LARGE が指定された際、それを何バイトのデータとして見積もるか。

その他については input.estimator.tiny と同様。

既定値: +Inf (無限大)

operator.join.broadcast.limit

@MasterJoin 系の演算子で、broadcast joinアルゴリズムを利用して結合を行うための、マスタ側の最大入力データサイズ。

基本的には input.estimator.tiny で指定した値の2倍程度にしておくのがよい。

既定値: 20971520 (20MB)

operator.estimator.<演算子注釈名>

指定した演算子の入力に対する出力データサイズの割合。

「演算子注釈名」には演算子注釈の単純名 ( Extract , Fold など) を指定し、値には割合 ( 1.0 , 2.5 など) を指定する。

たとえば、「 operator.estimator.CoGroup 」に 5.0 を指定した場合、すべての @CoGroup 演算子の出力データサイズは、入力データサイズの合計の5倍として見積もられる。

既定値: operator.estimator.* のデフォルト値 を参照

<バッチID>:<オプション名>

指定のオプションを、指定のIDのバッチに対してのみ有効にする。

バッチIDは spark. などのプレフィックスが付与する まえの ものを指定する必要がある。

既定値: N/A

spark.input.direct

ジョブフローの入力データを（可能ならば）Sparkから直接読むかどうか。

これが有効である場合、Direct I/Oではprologueフェーズを省略してSparkから直接ファイルを読み出す。

WindGateの場合はどちらもSparkからは読み出さず、WindGateのプログラムを利用してファイルシステム上に展開する。

既定値: true

spark.output.direct

ジョブフローの出力データを（可能ならば）Sparkから直接書き出すかどうか。

これが有効である場合、Direct I/Oではepilogueフェーズを省略してSparkから直接ファイルを書き出す。

WindGateの場合はどちらもSparkからは書き出さず、WindGateのプログラムを利用して外部リソース上に展開する。

既定値: true

Deprecated

Asakusa Framework バージョン 0.10.0 以降、 spark.input.direct および spark.output.direct を false に指定した利用は非推奨となりました。

spark.input.direct , spark.output.direct のいずれかの値を false に設定した場合、 YAESSによるバッチアプリケーション実行にはHadoopコマンドを利用できる環境が必要です。利用するHadoopコマンドの設定方法や検索方法については、 YAESSユーザーガイド を参照してください。

spark.parallelism.limit.tiny

Sparkでシャッフル処理を行う際に、データサイズの合計が指定のバイト数以下であれば分割数を1に制限する。

データサイズにはバイト数か、 +Inf (無限大)、 NaN (無効化) のいずれかを指定する。

データサイズは、 input.estimator.tiny などで指定した見積もりを利用する。

既定値: 20971520 (20MB)

spark.parallelism.limit.small

Sparkでシャッフル処理を行う際に、データサイズの合計が指定のバイト数以下であれば分割数を規定の 0.5 倍に設定する。

その他については spark.parallelism.limit.tiny と同様。

既定値: NaN (無効化)

spark.parallelism.limit.regular

Sparkでシャッフル処理を行う際に、データサイズの合計が指定のバイト数以下であれば分割数を規定の 1.0 倍に設定する。

その他については spark.parallelism.limit.tiny と同様。

標準では +Inf が指定されているため、下記の large や huge を利用したい場合には有限の値を指定する必要がある。

既定値: +Inf (無限大)

spark.parallelism.limit.large

Sparkでシャッフル処理を行う際に、データサイズの合計が指定のバイト数以下であれば分割数を規定の 2.0 倍に設定する。

その他については spark.parallelism.limit.tiny と同様。

既定値: +Inf (無限大)

spark.parallelism.limit.huge

Sparkでシャッフル処理を行う際に、データサイズの合計が指定のバイト数以下であれば分割数を規定の 4.0 倍に設定する。

その他については spark.parallelism.limit.tiny と同様。

通常の場合、この設定がもっとも大きなデータサイズを表すため、 +Inf から変更しない方がよい。

既定値: +Inf (無限大)

spark.parallelism.operator.<演算子>

指定の演算子を含むSparkのステージに対し、入力データサイズを強制的に指定する。

データサイズは tiny , small , regular , large , huge のいずれかから指定し、それぞれシャッフル時の分割数が 1 , 0.5 倍, 1.0 倍, 2.0 倍, 4.0 倍に設定される。

同一のステージに対して複数の演算子のデータサイズが指定された場合、そのうちもっとも大きなものが利用される。

既定値: N/A

spark.planning.option.unifySubplanIo

Sparkの等価なステージの入出力を一つにまとめる最適化を有効にするかどうか。

true ならば有効にし、 false ならば無効にする。

無効化した場合、ステージの入出力データが増大する場合があるため、特別な理由がなければ有効にするのがよい。

既定値: true

spark.planning.option.checkpointAfterExternalInputs

ジョブフローの入力の直後にチェックポイント処理を行うかどうか。

true ならばチェックポイント処理を行い、 false ならば行わない。

チェックポイント処理を行う場合、入力データの保存が余計に行われるため、特別な理由がなければ無効にするのがよい。

なお、Direct I/Oのオリジナルデータを2回以上読みたくない場合にチェックポイント処理が有効な場合があるが、その場合には spark.input.direct を無効にした方が多くの場合で効率がよい。

既定値: false

operator.estimator.* のデフォルト値

operator.estimator.* のデフォルト値

演算子注釈名

計算式

Checkpoint

入力の 1.0 倍

Logging

入力の 1.0 倍

Branch

入力の 1.0 倍

Project

入力の 1.0 倍

Extend

入力の 1.25 倍

Restructure

入力の 1.25 倍

Split

入力の 1.0 倍

Update

入力の 2.0 倍

Convert

入力の 2.0 倍

Summarize

入力の 1.0 倍

Fold

入力の 1.0 倍

MasterJoin

トランザクション入力の 2.0 倍

MasterJoinUpdate

トランザクション入力の 2.0 倍

MasterCheck

トランザクション入力の 1.0 倍

MasterBranch

トランザクション入力の 1.0 倍

Extract

既定値無し

GroupSort

既定値無し

CoGroup

既定値無し

既定値がない演算子に対しては、有効なデータサイズの見積もりを行いません。

制限事項

ここでは、Asakusa on Spark固有の制限事項について説明します。これらの制限は将来のバージョンで緩和される可能性があります。

互換性について

ここではAsakusa on Sparkを利用する場合に考慮すべき、Asakusa Frameworkやバッチアプリケーションの互換性について説明します。

演算子の互換性

Asakusa on Sparkでは、バッチアプリケーション内の演算子内に定義したstaticフィールドを複数のスレッドから利用する場合があります。このため、演算子クラス内でフィールドにstaticを付与している場合、staticの指定を除去するかフィールド参照がスレッドセーフになるようにしてください。

Asakusa on Spark Iterative Extensions

この文書では、Asakusa on Sparkの拡張機能「Iterative Extensions」について説明します。

Experimental

Asakusa Framework バージョン 0.10.3 では、 Asakusa on Spark Iterative Extensions は試験的機能として提供しています。

概要

Iterative Extensionsは、あるバッチに対してバッチ引数の一部または全部を変えながら同じバッチを連続して実行するための機能です。

Iterative Extensionsを適用したバッチを「反復バッチ」と呼びます。反復バッチは通常のバッチを連続して実行する場合と比べて、次の点で高速に実行できる可能性があります。

連続処理によるリソースの効率的な利用

連続するバッチアプリケーションを1つのSparkアプリケーションとして実行するため、特にYARN上での実行においては、アプリケーションコンテナの初期化などの分散オーバーヘッドが極小化される、コンテナリソースをシンプルな設定で最大限に利用できる、などの利点があります。

差分処理による最適化

反復バッチでは連続するバッチ間で再計算が不要な箇所は実行結果を再利用することがあるため、特に実行するバッチアプリケーション間での変更箇所が少ない場合には、バッチ間の差分処理による利点が大きくなります。

反復バッチは、日付範囲を指定した日次バッチの一括実行や、パラメータ・スイープによるシミュレーションといった用途に適しています。

Iterative Extensionsは、反復バッチを定義するためのAsakusa DSLの拡張構文、反復バッチを生成するするためのAsakusa DSLコンパイラの拡張、および反復バッチを実行するためのインターフェースや実行モジュールなどを提供します。

Attention

現時点では、Iterative Extensions は Asakusa on Spark 上でのみ使用できます。 MapReduce実行環境に対してIterative Extensionsに対応する予定はありません。

反復バッチの開発

反復バッチを作成するには、 Iterative Extensions用の構文 を利用して、 反復バッチの定義 、反復演算の定義 を行います。

反復バッチ固有の定義以外は、通常のAsakusa DSLを使ったバッチアプリケーションの開発方法と同じです。

Iterative Extensions用の構文

Asakusa Framework バージョン 0.8.0 以降では、Asakusa DSLに対して以下の構文を利用することができます。

反復バッチ注釈 - @IterativeBatch 1

対象の ジョブフロー が反復バッチであることを表す注釈。

ジョブフロークラスに反復バッチ注釈 IterativeBatch を指定し、アプリケーションのDSLコンパイルを実行すると該当のジョブフローから反復バッチを生成します。

Attention

反復バッチ注釈はバッチクラスではなく、ジョブフロークラスに指定します。反復バッチでは Batch DSL は使用しません。

反復化注釈 - @Iterative 2

対象の処理 (外部入力、演算子) が反復対象であることを表す注釈。

ジョブフロークラスのジョブフローコンストラクタや演算子クラス、演算子メソッドに反復化注釈 Iterative を指定することで、その処理が反復処理の対象となります。

反復化注釈には、その要素に反復の対象となる変数を表す反復変数名を指定することができます。

1

com.asakusafw.vocabulary.iterative.IterativeBatch [https://docs.asakusafw.com/0.10.3/release/api/com/asakusafw/vocabulary/iterative/IterativeBatch.html]

2

com.asakusafw.vocabulary.iterative.Iterative [https://docs.asakusafw.com/0.10.3/release/api/com/asakusafw/vocabulary/iterative/Iterative.html]

反復バッチの定義

反復バッチを定義するには、ジョブフロークラスに対して反復バッチ注釈 IterativeBatch を指定します。この注釈の要素 name に反復バッチの名前を指定します。この名前は反復バッチのバッチIDとして使用されます 3 。

@IterativeBatch(name = "hogeIterativeBatch")
public class HogeJobFlow extends FlowDescription {
    ...
}

既存のジョブフロークラス ( 注釈 JobFlow を指定したクラス ) に反復バッチ注釈を指定することもできます。この場合、このジョブフロークラスは通常のバッチにおけるジョブフロー、および反復バッチの両方の要素として利用することができます。

@JobFlow(name = "hogeJobflow")
@IterativeBatch(name = "hogeIterativeBatch")
public class HogeJobFlow extends FlowDescription {
    ...
}

3

反復バッチのフローIDには自動的に main という値が設定されます。

反復演算の定義

反復バッチの中で反復対象となる箇所を「反復演算」として定義します。

反復演算には、 外部入力の反復 と 演算子の反復 を定義することができます。

また、反復演算の指定時に 反復変数の指定 を行うことで、繰り返し処理時に不必要な再処理を行わず、演算処理の結果を再利用するといった最適化が得られる可能性があります。

反復演算を含むデータフローは、 反復演算の対象範囲 に従って反復処理が行われます。

外部入力の反復

外部入力の反復は、Direct I/O を使った外部入力処理に対して、バッチ引数を変更しつつ連続して入力処理を実行するよう指定します。外部入力の反復は主に入力の対象や範囲をパラメータによって切り替えながら実行する、といった場合に利用します。

例えばDirect I/Oでは、入力ファイルのベースパスやファイル名のパターン文字列の一部などをバッチ引数の値で置き換えることができますが、反復バッチによってこれらのパラメータを変更しつつ連続で入力処理を実行できるようになります 4 。

外部入力の反復を指定するには、 反復バッチの定義 で定義したジョブフロークラスのジョブフローコンストラクタ内で、反復演算の対象とする入力（ 注釈 Import を指定している仮引数）の先頭に反復化注釈 Iterative を指定します。

@IterativeBatch(name = "hogeIterativeBatch")
public class HogeJobFlow extends FlowDescription {
    ...
    public HogeJobFlow(
            @Iterative @Import(name = "foo", description = "FooImporter.class") In<Foo> input,
            ...) {
        ...
    }
    ...
}

Attention

現時点では、WindGate, ThunderGateによる外部入力はIterative Extensionsに対応していません。これらの外部入力に反復化注釈を設定した場合はDSLコンパイルエラーとなります。

Attention

Interative ExtensionsはSparkの実行環境にのみ対応しています。このため外部入力の反復を利用する場合は、コンパイルオプション spark.input.direct 5 を false に設定した、 MapReduce上でDirect I/Oの入力処理を実行する機能は利用できません。コンパイルオプション spark.input.direct を false に設定した場合はDSLコンパイルエラーとなります。

4

Direct I/O の入力時にバッチ引数が利用可能な項目については Direct I/O ユーザーガイド などを参照してください。

5

コンパイルオプション spark.input.direct については、 Asakusa on Spark リファレンス のコンパイラプロパティの項を参照してください。

演算子の反復

演算子の反復は、バッチ引数を利用する処理を記述したユーザ演算子に対して、バッチ引数を変更しつつ連続して演算子の処理を実行するよう指定します。外部入力の反復は主に入力データを切り替えるのに対して、演算子の反復は演算子内のロジックで使用するパラメータを切り替える場合に利用します。

ユーザ演算子の演算子メソッド内ではコンテキストAPIを使ってバッチ引数を取得することができますが、反復バッチによってコンテキストAPIから取得するバッチ引数の値を変更しつつ連続で演算子の処理を実行することができるようになります 6 。

演算子の反復を指定するには、反復演算の対象とするユーザ演算子に対して、演算子注釈の前に反復化注釈 Iterative を指定します。

public abstract class HogeOperators {
    ...
    @Iterative
    @Update
    public void hogeOperator(Bar bar) {
        String iterativeParameter = BatchContext.get("<iterative-parameter-key>");
        ...
    }
    ...
}

6

コンテキストAPIの使い方については Asakusa DSLユーザーガイド などを参照してください。

反復変数の指定

バッチ引数のうち、反復バッチによって連続処理の都度変更の対象となるバッチ引数を「反復変数」と呼びます。通常のバッチでは複数のバッチ引数を指定できるのと同様に、反復バッチでは複数の反復変数を設定することができます。

反復バッチ内のある反復演算内では、反復バッチに与えた反復変数に対して一部の反復変数のみを利用する場合があります。そのような反復演算については、反復演算の定義時にその処理内で利用する反復変数を指定しておくことで、不要な再処理を実行しないような最適化が得られる可能性があります。

反復演算に対して反復変数を指定するには、反復化注釈 Iterative の要素に反復変数名を指定します。反復変数名は複数指定が可能です。

public abstract class HogeOperators {
    ...
    @Iterative({ "iterative-param1", "iterative-param2" })
    @Update
    public void hogeOperator(Bar bar) {
        String iterativeParameter1 = BatchContext.get("iterative-param1");
        String iterativeParameter2 = BatchContext.get("iterative-param2");
        ...
    }
    ...
}

なお、反復化注釈に反復変数を設定しない場合は、その反復演算は連続処理の都度、常に再処理が必要であるものとして扱われます。

反復演算の対象範囲

データフロー内で、ある反復演算に後続する演算子の処理は自動的に反復演算となります。

このような演算子内では、明示的に反復演算の指定を行なわなくても反復変数を利用することができます。

外部出力の反復

外部出力の反復は、Direct I/O を使った外部出力処理に対して、バッチ引数を変更しつつ連続して出力処理を実行します。

外部出力に接続されるデータフロー内で外部入力の反復や反復演算が実行された場合、外部出力の入力ファイルのベースパスやファイル名のパターン文字列の一部などに反復変数を設定していると、これを反復演算として処理します。

なお、外部出力は明示的に反復演算として定義することはできません。外部入力と同様の方法で反復化注釈を外部出力に指した場合はDSLコンパイルエラーとなります。

Attention

現時点では、WindGate, ThunderGateによる外部出力はIterative Extensionsに対応していません。これらの外部出力を利用する場合、外部入力と外部出力で同じバッチ引数を使用している場合において外部入力を反復演算としても、外部出力側では反復化の対象とはならないことに注意してください。

Attention

Interative ExtensionsはSparkの実行環境にのみ対応しています。このため外部出力の反復を利用する場合は、コンパイルオプション spark.output.direct 7 を false に設定した、 MapReduce上でDirect I/Oの出力処理を実行する機能は利用できません。

Note

Asakusa on Spark バージョン 0.3系では、外部出力の反復はIterative Extensionsに対応していませんでした。

Asakusa on Spark バージョン 0.4.0 からは上述の通り、Direct I/Oを外部出力に利用する場合においてIterative Extensionsに対応するようになりました。

7

コンパイルオプション spark.output.direct については、 Asakusa on Spark リファレンス のコンパイラプロパティの項を参照してください。

反復バッチのテスト

現時点では、Iterative Extensionsでは反復バッチ特有のテスト機能は提供していません。

反復バッチをテストする方法として、反復バッチのジョブフロークラスを通常のジョブフローとしてテストする方法があります。テストドライバ上から実行する場合、パラメータの反復をテスト上で再現することはできませんが、単一のパラメータセットに対してのテストは可能です。

Tip

反復バッチ専用のジョブフロークラスを作成した場合、テストドライバ上でテストを実行するのみの目的で 注釈 JobFlow を付与するのは望ましくないかもしれません。その場合、 FlowPartTester を使って対象のジョブフロークラスをフロー部品としてテストを実行する方法があります。

反復バッチのビルド

反復バッチのビルド方法は通常のバッチアプリケーションのビルド手順と同じです。

ビルド用のGradleタスクとして sparkCompileBatchapps や assemble を利用することができます。これらのタスクを実行すると、アプリケーションプロジェクトの build/spark-batchapps 配下にビルド済みのバッチアプリケーションが生成されます。

なお、Asakusa on Spark Gradle Pluginを有効にしている場合、 assemble タスクによるデプロイメントアーカイブの作成時に反復バッチの実行に必要なモジュールが含まれるため、追加のライブラリ登録などは必要ありません。

アプリケーションのビルドやデプロイについては、 Asakusa on Spark ユーザガイド も参照してください。

反復バッチの実行

反復バッチは通常のバッチと同様にYAESSを使って実行することができますが、反復バッチ固有のパラメータが必要です。

変数表の作成

反復バッチ実行時に指定する反復変数の一覧を「変数表」と呼びます。

変数表は、JSON形式のUTF-8テキストファイルとして定義します。 1つのJSONオブジェクトに1回分のバッチ実行処理に必要なバッチ引数をプロパティとして定義します。

この1つのJSONオブジェクトで定義する、反復変数の一覧を一意に定めた1回分の処理を「ラウンド」と呼びます。変数表には、反復バッチ内の各ラウンドで使用する反復変数を定義したJSONオブジェクトを列挙します。

次の変数表の例では、反復変数 date を3ラウンド分定義しています。

{
    "date": "2011-04-01"
}
{
    "date": "2011-04-02"
}
{
    "date": "2011-04-03"
}

1ラウンド内で複数の反復変数を指定する場合は、次の例のように定義します。ここでは 反復変数 date と category に対してそれぞれ2つの値の組み合わせ、つまり4つのパターンを各ラウンドで実行します。

{
    "date": "2011-04-01",
    "category": "01"
}
{
    "date": "2011-04-01",
    "category": "02"
}
{
    "date": "2011-04-02",
    "category": "01"
}
{
    "date": "2011-04-02",
    "category": "02"
}

Attention

変数表のJSONファイルはJSONの配列ではなく、JSONのオブジェクトを列挙した形で指定してください。オブジェクトの区切りにカンマ等も不要です。

YAESSによる反復バッチの実行

反復バッチを実行するには、YAESSのオプションに 変数表の作成 で用意した変数表を指定します。

yaess-batch.sh のオプションに -X-parameter-table <変数表のファイルパス> という形式で変数表のファイルパスを指定することができます。

-X-parameter-table による変数表の指定と、-A <変数名>=<値> によるバッチ引数の指定を同時に行うこともできます。変数表内のバッチ引数と、 -A で指定するバッチ引数で同じ変数名の指定が存在した場合、変数表で指定する値が使用されます。

以下は、YAESSによる反復バッチの実行例です。

$ASAKUSA_HOME/yaess/bin/yaess-batch.sh hogeIterativeBatch -X-parameter-table $HOME/var/parameter-table.json

通常のバッチ引数と変数表を両方指定する場合は、以下のように指定します。

$ASAKUSA_HOME/yaess/bin/yaess-batch.sh hogeIterativeBatch -A foo=abc -X-parameter-table $HOME/var/parameter-table.json

反復バッチの実行時設定

反復バッチの実行時パラメータは、 Asakusa on Sparkの最適化設定 と同じ方法で設定することができます。

以下では反復バッチ固有の設定項目について説明します。

設定項目

com.asakusafw.spark.iterativebatch.slots

反復バッチ内で同時に実行するラウンド数を指定します。

このプロパティを設定しない場合、反復バッチの実行時にすべてのラウンドを同時に実行します。

既定値: Integer.MAX_VALUE

Hint

一部のケースにおいて、同時に実行するラウンド数が大きい場合にタスク数が膨大になることで、Sparkアプリケーションのパフォーマンスが劣化することがあることを確認しています。このような場合、com.asakusafw.spark.iterativebatch.slots を適切に設定することでパフォーマンスが改善する可能性があります。

com.asakusafw.spark.iterativebatch.stopOnFail

反復バッチ実行中のあるラウンドが異常終了した場合に、反復バッチ全体を異常終了するかを指定します。

標準の設定では、反復バッチ内であるラウンドが異常終了した場合は即時に反復バッチ全体を異常終了します。

この設定値を false にした場合、あるラウンドが異常終了しても他のラウンドの処理が続行されます。また反復バッチの実行結果 （正確には反復バッチ内の main フェーズ）は常に成功となります。

既定値: true

Attention

この設定値を false にした場合、一部、もしくは全てのラウンドが異常終了した場合でも、反復バッチの実行結果が成功となることに注意してください。各ラウンドの実行結果は、反復バッチの実行時ログなどを確認する必要があります。

リリースノート

Attention

Asakusa on Spark バージョン 0.4.0 以降のリリースノートは以下を参照してください

リリースノート

過去のリリースノート

Asakusa on Sparkの過去バージョンのリリースノートです。

すべての変更点一覧は Changelogs も参照してください。

Release 0.3.2

Dec 05, 2016

Asakusa on Spark 0.3.2 documentation [https://docs.asakusafw.com/asakusa-on-spark/0.3.2/release/ja/html/index.html]

Spark バージョン 1.6.3 に対応しました。

その他、Spark DSLコンパイラや実行ライブラリなどのバグフィックスが含まれます。

変更点の詳細は Changelogs を参照してください。

互換性に関して

Asakusa on Spark バージョン 0.3.2 は、 Asakusa Framework バージョン 0.8.2 以降が必要です。

Release 0.3.1

Jul 25, 2016

Asakusa on Spark 0.3.1 documentation [https://docs.asakusafw.com/asakusa-on-spark/0.3.1/release/ja/html/index.html]

新機能と主な変更点

Spark バージョン 1.6.2 に対応しました。

その他、細かな機能改善およびバグフィックスが含まれます。

すべての変更点は Changelogs を参照してください。

互換性に関して

Asakusa on Spark バージョン 0.3.1 は、 Asakusa Framework バージョン 0.8.1 以降が必要です。

Release 0.3.0

Apr 08, 2016

Asakusa on Spark 0.3.0 documentation [https://docs.asakusafw.com/asakusa-on-spark/0.3.0/release/ja/html/index.html]

新機能と主な変更点

正式機能として公開

2015年からDeveloper Previewとして公開していた Asakusa on Spark を、バージョン 0.3.0 より正式機能として公開しました。

Asakusa on Spark Iterative Extentions

Asakusa on Spark の拡張機能「Iterative Extensions」を試験的機能として公開しました。

Iterative Extensionsは、あるバッチに対してバッチ引数の一部または全部を変えながら同じバッチを連続して実行するための機能です。

Iterative Extensionsを適用したバッチを「反復バッチ」と呼びます。反復バッチは通常のバッチを連続して実行する場合と比べて、次の点で高速に実行できる可能性があります。

連続処理によるリソースの効率的な利用

連続するバッチアプリケーションを1つのSparkアプリケーションとして実行するため、特にYARN上での実行においては、アプリケーションコンテナの初期化などの分散オーバーヘッドが極小化される、コンテナリソースをシンプルな設定で最大限に利用できる、などの利点があります。

差分処理による最適化

反復バッチでは連続するバッチ間で再計算が不要な箇所は実行結果を再利用することがあるため、特に実行するバッチアプリケーション間での変更箇所が少ない場合には、バッチ間の差分処理による利点が大きくなります。

反復バッチは、日付範囲を指定した日次バッチの一括実行や、パラメータ・スイープによるシミュレーションといった用途に適しています。

Iterative Extensionsは、反復バッチを定義するためのAsakusa DSLの拡張構文、反復バッチを生成するするためのAsakusa DSLコンパイラの拡張、および反復バッチを実行するためのインターフェースや実行モジュールなどを提供します。

Asakusa on Spark Iterative Extensions の詳細は、以下のドキュメントを参照してください。

Asakusa on Spark Iterative Extensions

その他の変更点

Spark バージョン 1.6.1 に対応しました。

その他、細かな機能改善およびバグフィックスが含まれます。

すべての変更点は Changelogs を参照してください。

互換性に関して

Asakusa on Spark バージョン 0.3.0 は、 Asakusa Framework バージョン 0.8.0 以降が必要です。

Asakusa on Spark バージョン 0.3.0 は、 Spark バージョン 1.6.0 以降が必要です。

Note

対応プラットフォームの変更については、 Asakusa on Spark ユーザガイド - 対応プラットフォーム を参照してください。

Release 0.2.2

Feb 01, 2016

新機能と主な変更点

特定の条件でバッチアプリケーションのコンパイル時に大量のメモリを消費し、コンパイルに失敗することがある問題を修正しました。

また、この修正によりコンパイル速度が改善されます。

互換性に関して

Asakusa on Spark バージョン 0.2.2 は、 Asakusa Framework バージョン 0.7.6 以降が必要です。

Note

対応プラットフォームの変更については、 Asakusa on Spark ユーザガイド - 対応プラットフォーム を参照してください。

Release 0.2.1

Nov 19, 2015

新機能と主な変更点

Spark バージョン 1.5.2 に対応しました。

特定の条件でバッチアプリケーションのコンパイル、実行に失敗する問題を修正しました。

その他の変更点

多くの内部的な改善

互換性に関して

Asakusa on Spark バージョン 0.2.1 は、 Asakusa Framework バージョン 0.7.5 以降が必要です。

Note

対応プラットフォームの変更については、 Asakusa on Spark ユーザガイド - 対応プラットフォーム を参照してください。

Release 0.2.0

Sep 15, 2015

新機能と主な変更点

Spark バージョン 1.5.0 に対応しました。

動作検証のHadoopディストリビューションを更新しました。

その他の変更点

軽微な内部の改善

Release 0.1.2

Sep 10, 2015

バージョン 0.1.1 はリリースプロセスの問題により一部の機能が正しくリリース出来ていませんでした。

このバージョンはそのリリース上の問題のみを修正したリリースです。

Release 0.1.1

Aug 25, 2015

新機能と主な変更点

演算子の出力にファイルバッファを利用する設定を追加

実行時のパラメータに com.asakusafw.spark.fragment.bufferSize を追加しました。

このプロパティを設定した場合、演算子の処理中に出力に追加したデータモデルオブジェクトの個数がこのプロパティに設定した値を超えた時点で、出力の内容をファイル上のバッファに退避します。

ある演算子の出力サイズが大きくメモリ不足エラーが発生するような場合に、このプロパティを設定することで問題を回避できる可能性があります。

詳しくは、 Asakusa on Sparkの最適化設定 を参照してください。

その他の変更点

Direct I/O 入力フィルターが使用できない問題を修正

レポートAPIの実装を変更できない制限の解消

その他、多くの内部的な改善

互換性に関して

Asakusa on Spark バージョン 0.1.1 は、 Asakusa Framework バージョン 0.7.4 以降が必要です。

Release 0.1.0

Jun 26, 2015

初版リリース

Changelogs

Attention

Asakusa on Spark バージョン 0.4.0 以降のChangelogsは以下を参照してください

Changelogs

Release 0.3.2

Dec 05, 2016

[ asakusafw-spark milestone:0.3.2 [https://github.com/asakusafw/asakusafw-spark/issues?&q=milestone:0.3.2] ]

[ asakusafw-compiler milestone:0.3.2 [https://github.com/asakusafw/asakusafw-compiler/issues?&q=milestone:0.3.2] ]

Bundled Components

Component

Version

Asakusa Framework Core

0.8.2 (↑)

Asakusa Framework Language Toolset

0.3.2 (↑)

Release 0.3.1

Jul 25, 2016

[ asakusafw-spark milestone:0.3.1 [https://github.com/asakusafw/asakusafw-spark/issues?&q=milestone:0.3.1] ]

[ asakusafw-compiler milestone:0.3.1 [https://github.com/asakusafw/asakusafw-compiler/issues?&q=milestone:0.3.1] ]

Bundled Components

Component

Version

Asakusa Framework Core

0.8.1 (↑)

Asakusa Framework Language Toolset

0.3.1 (↑)

Release 0.3.0

Apr 08, 2016

[ asakusafw-spark milestone:0.3.0 [https://github.com/asakusafw/asakusafw-spark/issues?&q=milestone:0.3.0] ]

[ asakusafw-compiler milestone:0.3.0 [https://github.com/asakusafw/asakusafw-compiler/issues?&q=milestone:0.3.0] ]

Bundled Components

Component

Version

Asakusa Framework Core

0.8.0

Asakusa Framework Language Toolset

0.3.0

Release 0.2.2

Feb 01, 2016

[ asakusafw-spark milestone:0.2.2 [https://github.com/asakusafw/asakusafw-spark/issues?&q=milestone:0.2.2] ]

[ asakusafw-compiler milestone:0.2.2 [https://github.com/asakusafw/asakusafw-compiler/issues?&q=milestone:0.2.2] ]

Bundled Components

Component

Version

Asakusa Framework Core

0.7.6

Asakusa Framework Language Toolset

0.2.2

Release 0.2.1

Nov 19, 2015

[ asakusafw-spark milestone:0.2.1 [https://github.com/asakusafw/asakusafw-spark/issues?&q=milestone:0.2.1] ]

[ asakusafw-compiler milestone:0.2.1 [https://github.com/asakusafw/asakusafw-compiler/issues?&q=milestone:0.2.1] ]

Bundled Components

Component

Version

Asakusa Framework Core

0.7.5

Asakusa Framework Language Toolset

0.2.1

Release 0.2.0

Sep 15, 2015

[ asakusafw-spark milestone:0.2.0 [https://github.com/asakusafw/asakusafw-spark/issues?&q=milestone:0.2.0] ]

[ asakusafw-compiler milestone:0.2.0 [https://github.com/asakusafw/asakusafw-compiler/issues?&q=milestone:0.2.0] ]

Bundled Components

Component

Version

Asakusa Framework Core

0.7.4

Asakusa Framework Language Toolset

0.2.0

Release 0.1.2

Sep 10, 2015

This version is only fixed release problem on version 0.1.1.

Release 0.1.1

Aug 25, 2015

[ asakusafw-spark milestone:0.1.1 [https://github.com/asakusafw/asakusafw-spark/issues?&q=milestone:0.1.1] ]

[ asakusafw-compiler milestone:0.1.1 [https://github.com/asakusafw/asakusafw-compiler/issues?&q=milestone:0.1.1] ]

Bundled Components

Component

Version

Asakusa Framework Core

0.7.4

Asakusa Framework Language Toolset

0.1.1

Release 0.1.0

Jun 26, 2015

The first developer preview release of Asakusa on Spark.

Bundled Components

Component

Version

Asakusa Framework Core

0.7.3

Asakusa Framework Language Toolset

0.1.0

Asakusa on M³BP

Asakusa on M³BPは、Asakusa DSLを始めとするAsakusa Frameworkの開発基盤を利用して作成したバッチアプリケーションに対して、 M³ for Batch Processingをその実行基盤として利用するための機能セットを提供します。

Asakusa on M³BPの概要と利用方法は、 Asakusa on M3BPユーザーガイド を参照してください。

ドキュメント

Asakusa on M³BPユーザーガイド

Asakusa on M³BPの最適化設定

Asakusa on M³BPリファレンス

リリースノート

Changelogs

リソース

ソースリポジトリ

asakusafw-compiler (GitHub) [https://github.com/asakusafw/asakusafw-compiler]

asakusafw-m3bp (GitHub) [https://github.com/asakusafw/asakusafw-m3bp]

APIリファレンス

Asakusa on M3BP Gradle Plugins (Groovydoc) [https://docs.asakusafw.com/asakusa-on-m3bp/0.3.3/release/gradle-plugins/index.html]

リンク

M3 for Batch Processing (GitHub) [https://github.com/fixstars/m3bp]

Asakusa on M³BPユーザーガイド

この文書では、Asakusa on M³BPを利用してバッチアプリケーションをビルドし、実行する方法について説明します。

概要

Asakusa on M³BPは、Asakusa DSLを始めとするAsakusa Frameworkの開発基盤を利用して作成したバッチアプリケーションに対して、M³ for Batch Processing 1 をその実行基盤として利用するための機能セットを提供します。

M³ for Batch ProcessingはDAG (Directed Acyclic Graph; 有向非循環グラフ) の形で表現されたタスクをマルチコア環境で効率よく処理するためのフレームワークで、以下のような特徴があります。

単一ノード上のマルチコア/マルチプロセッサ用に最適化

細粒度で動的なタスクスケジューリング

ほぼすべてオンメモリで処理

上記のような特徴のため、Hadoop MapReduceやSparkに比べて、小〜中規模データサイズのバッチ処理に非常に適しています。

Asakusa Frameworkの適用領域においても、中間結果が全てメモリ上に収まる規模のバッチにおいてはAsakusa on Sparkよりも高速で、かつ高いコストパフォーマンスになることを確認しています 2 。

1

https://github.com/fixstars/m3bp

2

http://www.asakusafw.com/techinfo/reference.html

構成

Asakusa on M³BPを利用する場合、従来のAsakusa Frameworkが提供するDSLやテスト機構をそのまま利用して開発を行います。アプリケーションをビルドして運用環境向けの実行モジュール（デプロイメントアーカイブ）を作成する段階ではじめてAsakusa on M³BPのDSLコンパイラ(DSL Compiler for M³BP)を利用します。

また、DSL Compiler for M³BPで生成したバッチアプリケーションは、従来と同様にYAESSを利用して実行できます。このとき、MapReduceやSparkと異なり、実行基盤にHadoopを必要としません (Hadoopとの連携により、HDFS等を利用することもできます)。

Asakusa DSL

従来のAsakusa DSLやDMDLで記述したバッチアプリケーションは基本的に変更なしで、DSL Compiler for M³BPを利用してM³ for Batch Processing上で実行可能なジュールを生成することができます。

テスト機構

従来のAsakusa DSLのテスト方法と同様に、テストドライバーを利用してAsakusa DSLのテストを実行することができます。このとき、Asakusa on M³BPは特に利用しません。

アプリケーションの実行

従来と同様、YAESSを利用してバッチアプリケーションを実行することができます。実行環境にMapReduce用、Spark用、M³ for Batch Processing用のバッチアプリケーションをすべて配置して運用することも可能です。

外部システム連携

Direct I/OやWindGateといった外部システム連携モジュールはAsakusa on M³BPのバッチアプリケーションでもそのまま利用することができます。

Attention

Asakusa on M³BPを利用する上でもWindGateなどの外部システム連携機能において、一部Hadoopの機能を利用します。

対応プラットフォーム

実行環境

Asakusa on M³BPは、今のところ64ビットx86アーキテクチャのLinux環境 (以下、Linux x64)上のみで動作の確認を行っています。

Asakusa on M³BPのアプリケーションを実行する場合、以下または互換のソフトウェアが必要になります。

Java SE Development Kit 8 Update 74 (Linux x64)

GNU C++ Library 4.8.5 (libstdc++.so.6)

GNU C Library 2.17 (libc.so.6)

Portable Hardware Locality 1.7 (libhwloc.so.5) 3

Hint

上記の構成は、Red Hat Enterprise Linux 7.2 (またはCentOS 7.2などのクローン)を想定しています。これらのディストリビューションを利用している場合、標準のパッケージ管理ツールで上記の一部を導入できます。

3

https://www.open-mpi.org/projects/hwloc/

Hadoopディストリビューション

Asakusa on M³BPは、実行環境にインストールされたHadoopと連係して動作することもできます。

以下のような機能を利用できます。

Direct I/O

入出力データソースに、HDFSやその他のHadoopが対応しているファイルシステムを利用

WindGate

HDFSを経由してWindGateの入出力を授受

Hadoopとの連携方法は、 Hadoopとの連携 を参照してください。

Asakusa on M³BPが動作を検証しているHadoopディストリビューションは、対応プラットフォーム の「Hadoopディストリビューション」を参照してください。

Attention

Asakusa on M³BP をMapRと連携して利用する場合において、バッチアプリケーションの起動時にデッドロックが発生しアプリケーションが実行されないことがある問題を確認しています。この問題の回避方法について Hadoopとの連携 に記載しています。

開発環境の構築

バッチアプリケーションの開発環境には、通常のAsakusa Frameworkの開発環境に加え、実行環境上で動作するネイティブライブラリをビルドするための環境が必要となります。

Asakusa on M³BPを利用して実行モジュールを作成するには、以下または互換のソフトウェアが必要になります。

Java SE Development Kit 8 Update 74

CMake 2.8 4

GNU Make 3.82 5

GNU Compiler Collection 4.8.5 (Linux x64) 6

gcc

g++

Attention

ビルド環境と実行環境が異なる場合、実行環境で動作するオブジェクトコードを生成するためのクロスコンパイラが必要になります。オブジェクトコードの生成時にはCMakeを内部的に利用しているため、クロスコンパイラの設定もCMakeの機能を利用して行うことができます。

クロスコンパイラを導入したら、DSL Compiler for M³BPのコンパイラオプション m3bp.native.cmake.CMAKE_TOOLCHAIN_FILE にCMakeのツールチェインファイルを指定してください。

参考URL: https://cmake.org/Wiki/CMake_Cross_Compiling

Hint

通常のAsakusa Frameworkの開発環境を準備するには以下のドキュメントなどを参考にしてください。

Asakusa Framework スタートガイド

Asakusa Framework チュートリアル [https://docs.asakusafw.com/basic-tutorial/0.10/release/ja/html/index.html]

4

https://cmake.org/

5

https://www.gnu.org/software/make/

6

https://gcc.gnu.org/

アプリケーションの開発

開発環境上で Asakusa Frameworkのバッチアプリケーションを開発し、Asakusa on M³BPのアプリケーションをビルドする方法を見ていきます。

プロジェクトテンプレート

Asakusa on M³BPを利用する構成を持つアプリケーション開発用のプロジェクトテンプレートは、以下リンクからダウンロードします。

asakusa-m3bp-template-0.10.3.tar.gz [http://www.asakusafw.com/download/gradle-plugin/asakusa-m3bp-template-0.10.3.tar.gz]

See also

プロジェクトテンプレートの構成や利用方法については、 Asakusa Gradle Plugin ユーザーガイド を参照してください。

サンプルアプリケーション

サンプルプログラム集 (GitHub) [http://github.com/asakusafw/asakusafw-examples] に含まれるプロジェクト example-basic-m3bp は Asakusa on M³BPを利用する基本的なサンプルアプリケーションプロジェクトです。

このプロジェクトは Asakusa on M³BP用のプロジェクトテンプレートに対して、 Asakusa Framework スタートガイド などで説明しているサンプルアプリケーション「カテゴリー別売上金額集計バッチ」用のソースコードが追加されています。

Asakusa on M³BP Gradle Plugin

Asakusa on M³BP Gradle Pluginは、アプリケーションプロジェクトに対してAsakusa on M³BPのさまざまな機能を追加します。

プロジェクトテンプレート や サンプルアプリケーション で紹介したプロジェクトには、 Asakusa on M³BP Gradle Pluginがあらかじめ利用可能になっています。

その他のプロジェクトで Asakusa on M³BP Gradle Pluginを有効にするには、アプリケーションプロジェクトのビルドスクリプト ( build.gradle )に対して以下の設定を追加します。

apply plugin: 'asakusafw-m3bp'

以下はAsakusa on M³BP Gradle Pluginの設定を追加したビルドスクリプトの例です。

build.gradle

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.3'
    }
}

apply plugin: 'asakusafw-sdk'
apply plugin: 'asakusafw-organizer'
apply plugin: 'asakusafw-m3bp'
apply plugin: 'eclipse'

See also

Asakusa on M³BP Gradle Pluginのより詳細な情報は、 Asakusa Gradle Plugin リファレンス や Asakusa on M3BPリファレンス などを参照してください。

アプリケーションのビルド

Asakusa on M3BP Gradle Plugin を設定した状態で、Gradleタスク m3bpCompileBatchapps を実行すると、Asakusa on M³BP向けのバッチアプリケーションのビルドを実行します。

./gradlew m3bpCompileBatchapps

m3bpCompileBatchapps タスクを実行すると、アプリケーションプロジェクトの build/m3bp-batchapps 配下にビルド済みのバッチアプリケーションが生成されます。

標準の設定では、Asakusa on M³BPのバッチアプリケーションは接頭辞に m3bp. が付与されます。例えば、サンプルアプリケーションのバッチID example.summarizeSales の場合、Asakusa on M³BPのバッチアプリケーションのバッチIDは m3bp.example.summarizeSales となります。

See also

DSL Compiler for M³BPで利用可能な設定の詳細は、 Asakusa on M3BPリファレンス を参照してください。

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

Asakusa on M3BP Gradle Plugin を設定した状態で、Asakusa Frameworkのデプロイメントアーカイブを作成すると、Asakusa on M³BPのバッチアプリケーションアーカイブを含むデプロイメントアーカイブを生成します。

デプロイメントアーカイブを生成するには Gradleの assemble タスクを実行します。

./gradlew assemble

Hint

Shafuを利用する場合は、プロジェクトを選択してコンテキストメニューから Jinrikisha (人力車) ‣ Asakusaデプロイメントアーカイブを生成 を選択します。

Hadoopとの連携

Attention

Hadoopとの連携についての標準の動作および設定は、Asakusa Framework バージョン 0.10.0 から大きく変更されました。バージョン0.9系、およびそれ以前のバージョンから移行する場合、必ず Asakusa Gradle Plugin バージョン 0.10系 の変更点 を参照してください。

デプロイメントアーカイブの生成を行う際に、標準の設定では実行環境上にインストールしたHadoopと連携するようデプロイメントアーカイブを生成します。実行環境上にインストールしたHadoopと連携することで、環境上に構築されているHDFSなどに対してファイルの入出力を行うことができるようになります。

実行環境にインストールされたHadoopを利用する際、以下の順序で hadoop コマンドを探して利用します (上にあるものほど優先度が高いです)。

環境変数に HADOOP_CMD が設定されている場合、 $HADOOP_CMD コマンドを経由して起動します。

環境変数に HADOOP_HOME が設定されている場合、 $HADOOP_HOME/bin/hadoop コマンドを経由して起動します。

hadoop コマンドのパスが通っている場合、 hadoop コマンドを経由して起動します。

Warning

多くのHadoopコマンドは、Java VMのヒープ容量の最大値に非常に小さな値を標準で指定します。この設定を上書きする方法は、 Java VMの設定 を参照してください。

Attention

MapRなどの一部の環境では、バッチアプリケーション起動時にデッドロックが発生しアプリケーションが正しく実行されないことがある問題が確認されています。これを回避するには、 build.gradle に以下の設定を加えてください

build.gradle

asakusafwOrganizer {
    extension {
        libraries += ["com.asakusafw.m3bp.bridge:asakusa-m3bp-workaround-hadoop:${asakusafw.m3bp.version}"]
    }
}

また、実行環境のHadoopと連携せずローカルファイルシステムや外部のデータベースに対してのみデータの入出力を行うような場合でも、 Direct I/OやWindGateなどの一部のコンポーネントはHadoopに含まれるライブラリやスクリプトを必要とするため、実行環境上にはAsakusa Frameworkの実行に必要なHadoopコンポーネントを導入する必要があります。

このような場合 Asakusa Gradle Plugin の機能で、必要な最低限のHadoopライブラリーをデプロイメントアーカイブに組み込むことができます。デプロイメントアーカイブにHadoopライブラリーを含めるには、以下の設定を追加してください。

asakusafwOrganizer.hadoop.embed true

以下は、 prod プロファイルのデプロイメントアーカイブに対してのみ上記の設定を行う例です。

build.gradle

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.3'
    }
}

apply plugin: 'asakusafw-sdk'
apply plugin: 'asakusafw-organizer'
apply plugin: 'asakusafw-m3bp'
apply plugin: 'eclipse'

asakusafwOrganizer {
    profiles.prod {
        hadoop.embed true
    }
}

Attention

この方法で導入されるHadoopはAsakusa Frameworkの実行に最低限必要なコンポーネントのみが含まれます。特にHDFSなどのHadoopファイルシステム実装ライブラリが含まれないなどの制約があるため、実行環境上のHadoopファイルシステムと連携する場合にはこのオプションを有効にせず、実行環境上にインストールしたHadoopと連携するようにしてください。

Tip

バッチアプリケーション実行時の環境変数は、YAESSプロファイルで設定することも可能です。

Asakusa on M³BPを利用する場合、コマンドラインジョブのプロファイル command.m3bp が利用できます。 $ASAKUSA_HOME/yaess/conf/yaess.properties に command.m3bp.env.HADOOP_CMD といったような設定を追加することで、YAESSからAsakusa on M³BPを実行する際に環境変数が設定されます。

YAESSのコマンドラインジョブの設定方法について詳しくは、 YAESSユーザーガイド - コマンドラインジョブの実行 などを参照してください。

アプリケーションの実行

ここでは、Asakusa on M³BP固有の実行環境の設定について説明します。

Asakusa Frameworkの実行環境の構築方法やバッチアプリケーションを実行する方法の基本的な流れは、 Asakusa Framework デプロイメントガイド などを参照してください。

バッチアプリケーションの実行

デプロイしたバッチアプリケーションをYAESSを使って実行します。

$ASAKUSA_HOME/yaess/bin/yaess-batch.sh コマンドに実行するバッチIDとバッチ引数を指定してバッチを実行します。標準の設定では、Asakusa on M³BPのバッチアプリケーションはバッチIDの接頭辞に m3bp. が付与されているので、このバッチIDを指定します。

Attention

標準の設定では、バッチIDの接頭辞に m3bp. がついていないバッチIDは従来のHadoop MapReduce向けバッチアプリケーションです。YAESSの実行時にバッチIDの指定を間違えないよう注意してください。

例えば、サンプルアプリケーションを実行する場合は、以下のように yaess-batch.sh を実行します。

$ASAKUSA_HOME/yaess/bin/yaess-batch.sh m3bp.example.summarizeSales -A date=2011-04-01

See also

サンプルアプリケーションのデプロイやデータの配置、実行結果の確認方法などは、 Asakusa Framework スタートガイド - サンプルアプリケーションの実行 を参照してください。

Attention

Asakusa on M³BPではメモリ上に中間データを配置するため、入力データが膨大であったり中間データが膨らむようなバッチ処理では、メモリ容量が不足してしまう場合があります。この場合、バッチ処理はエラーにより中断されます。

空きメモリ容量を増やすか、またはAsakusa on Sparkなどの利用を検討してください。

この制約は将来緩和される可能性があります。

Java VMの設定

Asakusa on M³BPでバッチアプリケーションを実行する際には、Java VMをひとつ起動してそのプロセス内でM³ for Batch ProcessingやAsakusaの演算子を実行します。

このとき、対象のJava VMを起動する際のオプション引数を、環境変数 ASAKUSA_M3BP_OPTS で指定できます。

以下は環境変数の設定例です。

export ASAKUSA_M3BP_OPTS='-Xmx16g'

上記のように書いた場合、Javaのヒープ領域の最大値を 16GB に設定できます。

実行コマンドの設定

Asakusa on M³BP実行用のJVMプロセスを起動するJavaコマンドは、環境変数 JAVA_CMD で設定することができます。 JAVA_CMD が未設定の場合、 PATH 環境変数に含まれる java コマンドが使用されます。

Hadoopとの連携 を設定した場合、Asakusa on M³BP実行用のJVMプロセスを起動するコマンドには hadoop コマンドが使用されます。この場合に利用される hadoop コマンドの検索方法は Hadoopとの連携 の説明を参照してください。

環境変数 ASAKUSA_M3BP_LAUNCHER は実行コマンドの先頭に任意のコマンド文字列を追加します。

ログの設定

Asakusa on M³BPの実行時のログ設定は、Logback設定ファイル $ASAKUSA_HOME/m3bp/conf/logback.xml で設定します。

Attention

Hadoopとの連携 を設定してバッチアプリケーションを実行した際に、利用する環境によってはバッチアプリケーションのログがHadoopのログ設定の上で出力される可能性があります。

Asakusa on M³BPのログ設定を優先したい場合は、環境変数 HADOOP_USER_CLASSPATH_FIRST=true を設定してください。

Asakusa on M³BPの最適化設定

この文書では、Asakusa on M³BPのバッチアプリケーション実行時の最適化設定について説明します。

設定方法

Asakusa on M³BPのバッチアプリケーション実行時の設定は、 設定ファイル を使う方法と 環境変数 を使う方法があります。

設定ファイル

Asakusa on M³BPに関するバッチアプリケーション実行時のパラメータは、 $ASAKUSA_HOME/m3bp/conf/m3bp.properties に記述します。このファイルは、Asakusa on M³BP Gradle Pluginを有効にしてデプロイメントアーカイブを作成した場合にのみ含まれています。

このファイルに設定した内容はAsakusa on M³BPのバッチアプリケーションの設定として使用され、バッチアプリケーション実行時の動作に影響を与えます。

設定ファイルはJavaのプロパティファイルのフォーマットと同様です。以下は m3bp.properties の設定例です。

m3bp.properties

## the max number of worker threads
com.asakusafw.m3bp.thread.max=10

## the default number of partitions
com.asakusafw.m3bp.partitions=10

環境変数

Asakusa on M³BPに関するバッチアプリケーション実行時のパラメータは、環境変数 ASAKUSA_M3BP_ARGS に設定することもできます。

環境変数 ASAKUSA_M3BP_ARGS の値には --engine-conf <key>=<value> という形式でパラメータを設定します。

以下は環境変数の設定例です。

export ASAKUSA_M3BP_ARGS='--engine-conf com.asakusafw.m3bp.thread.max=10'

設定ファイルと環境変数で同じプロパティが設定されていた場合、環境変数の設定値が利用されます。

Hint

環境変数による設定は、バッチアプリケーションごとに設定を変更したい場合に便利です。

Attention

yaess-batch.sh などのYAESSコマンドを実行する環境と、Asakusa on M³BPを実行する環境が異なる場合（例えばYAESSのSSH機能を利用している場合）に、 YAESSコマンドを実行する環境の環境変数がAsakusa on M³BPを実行する環境に受け渡されないことがある点に注意してください。

YAESSではYAESSコマンドを実行する環境の環境変数をYAESSのジョブ実行先に受け渡すための機能がいくつか用意されているので、それらの機能を利用することを推奨します。詳しくは YAESSユーザーガイド などを参照してください。

設定項目

Asakusa on M³BPのバッチアプリケーション実行時の設定項目は以下の通りです。

com.asakusafw.m3bp.thread.max

タスクを実行するワーカースレッドの最大数を設定します。

未設定の場合、利用可能な全てのCPUコアに対して一つずつワーカースレッドを割り当てます。

既定値: (論理コア数)

Hint

Asakusa on M³BPではこの値をCPUコア数より極端に大きな値にすると性能が低下する場合があります。計算ノードのCPUを占有できる環境では既定値を利用し、そうでない場合には既定値よりも小さな値を設定するとよいでしょう。

また、物理CPUコアに対して複数のスレッド(論理CPUコア)が存在する環境では、物理CPUコア数を設定した方が速くなるようなケースもあります。

com.asakusafw.m3bp.thread.affinity

各ワーカースレッドへのCPUコアの割り当て方法を設定します。

none

特別な設定を行わず、OSによるCPUコアの割り当てを利用します

compact

ワーカースレッドをCPUコアに割り当てる際に、同一ソケット上のコアから順番に割り当てていきます

scatter

ワーカースレッドをCPUコアに割り当てる際に、異なるソケットのコアを順番に割り当てていきます

既定値: none

Attention

この設定を有効(none以外)にした場合、Asakusa on M³BPはハードウェアの情報を参照します。仮想環境などでCPUコアの情報を正しく取得できない場合にはあまり効果がありません。

また、環境によってはnone以外を指定した際にエラーとなる場合があります。

com.asakusafw.m3bp.partitions

scatter-gather操作(シャッフル操作)のパーティション数を設定します。

既定値: (論理コア数の8倍)

Hint

この値はDAG上の各vertexの「タスク数」に大きな影響を与えます。基本的にscatter-gather操作の直後のvertexでは、パーティションごとにタスクが割り当てられて処理を行うため、上記パーティション数が少なすぎるとワーカースレッドに適切にタスクが行き渡りません。

また、ワーカースレッド数と同程度のパーティション数を指定した場合、各パーティションの大きさに偏り (キーの偏り) があるとワーカースレッドへタスクを均等に割り当てられなくなります。

多くの場合は、ワーカースレッド数の数倍を指定するのがよいでしょう。

com.asakusafw.m3bp.output.buffer.size

個々の出力バッファのサイズをバイト数で設定します。

既定値: 4194304 (4MB)

Hint

このバッファサイズは大きくしすぎると余計にメモリを消費し、小さくしすぎるとバッファを書き出す回数が増えて性能が低下する場合があります。

com.asakusafw.m3bp.output.buffer.records

個々の出力バッファの最大レコード数を設定します。

既定値: 524288

Hint

それぞれの出力バッファでは、ここで指定したレコード数が上限に達するか、または出力バッファの使用量がある閾値を超えるか、どちらかで出力バッファの内容を書き出しています。そのため、ここのレコード数を極端に小さな値に設定した場合、出力バッファに余裕があってもバッファの内容を頻繁に書き出してしまうことになります。

また、上記レコード数に応じてレコードのメタ情報を保持するため、極端に大きな値を指定すると余計にメモリを消費することになります。

個々のレコードが極端に小さかったり大きかったりすることが明らかな場合以外、この値を変更する必要はありません。

com.asakusafw.m3bp.output.buffer.flush

個々の出力バッファの内容を書き出す際の閾値となる使用量の割合を指定します。

この値には 0.0 から 1.0 までの値を指定できますが、実装によってはこれより狭い範囲の値に再設定される場合があります。

既定値: 0.8

Hint

それぞれの出力バッファでは、ここで指定したレコード数が上限に達するか、または出力バッファの使用量がある閾値を超えるか、どちらかで出力バッファの内容を書き出しています。そのため、ここの使用率の閾値に対して極端に小さな値に設定した場合、出力バッファに余裕があってもバッファの内容を頻繁に書き出してしまうことになります。

また、それぞれのレコードの(シリアライズ後の)サイズは、「 バッファサイズ * (1.0 - 使用率の閾値) 」以下である必要があります。これを超えた場合、レコードがバッファに収まらなくなって正常に動作しない場合があります。

個々のレコードが極端に小さかったり大きかったりすることが明らかな場合以外、この値を変更する必要はありません。

com.asakusafw.m3bp.buffer.access

個々の入出力バッファのアクセス方式を設定します。

nio

JavaのNIOを利用してバッファにアクセスします。

unsafe

Javaの非推奨の方法を利用してバッファにアクセスします。

既定値: nio (Java NIOを利用)

Deprecated

Asakusa Framework 0.10.0 以降、 com.asakusafw.m3bp.buffer.access に unsafe を指定することは非推奨となりました。

com.asakusafw.dag.input.file.directory

演算子リファレンス - 巨大な入力グループへの対応 などを利用してメモリ上のバッファをファイルとして退避する際に使用する、ファイルの出力先ディレクトリを設定します。

既定値: なし (未指定の場合、JVMのシステムプロパティ java.io.tmpdir で設定されているディレクトリを利用)

Attention

大量のバッファが出力されるような処理を実行する場合には、出力先に十分な空き領域を確保する必要があることに注意してください。

hadoop.<name>

指定の <name> を名前に持つHadoopの設定を追加します。

Asakusa on M³BPでは、一部の機能 (Direct I/Oなど) にHadoopのライブラリ群を利用しています。このライブラリ群がHadoopの設定を参照している場合、この項目を利用して設定値を変更できます。

Asakusa全体に関するHadoopの設定は $ASAKUSA_HOME/core/conf/asakusa-resources.xml 内で行えますが、同一の項目に対する設定が asakusa-resources.xml と hadoop.<name> の両方に存在する場合、後者の設定値を優先します。

Hint

Asakusa on M³BPに組み込まれたHadoopライブラリ群を利用する場合、システムにインストールされたHadoopの設定ファイルは利用されず、各Hadoopの既定値を利用します。このような場合、この設定項目を利用してHadoopの設定を上書きしてください。

また、システムにインストールされたHadoopを利用する場合にも、Asakusa on M³BP利用時のみ異なる設定を行うには、ここで指定するのがよいでしょう。

WindGate JDBC ダイレクト・モード

概要

WindGate JDBC ダイレクト・モードとは、WindGate を利用したバッチアプリケーションの実行時にデータフロー処理を行うプロセスの内部で直接WindGate JDBCによるデータベースへのインポート処理とエクスポート処理を行うように動作する最適化設定です。

通常のWindGateの動作は、バッチアプリケーションのメインとなるデータフローの処理の前後でそれぞれ WindGateのプロセスを起動し、外部リソースからのデータの読み込み（インポート処理）と書き出し（エクスポート処理）を行います。

メインとなるデータフロー処理とWindGateの処理との間ではHadoopファイルシステムを介した中間データの受け渡しが必要になります。また、インポート処理、データフロー処理、エクスポート処理はそれぞれのフェーズが完全に終了しないと次のフェーズに進むことができません。

これに対して「WindGate ダイレクト・モード」ではプロセス間の中間データの受け渡しは不要になり、フェーズ間の待ち合わせを設けないように設定することも可能です。これらの動作により、通常のWindGateよりもバッチアプリケーション全体の実行時間が大きく短縮できる可能性があります。

WindGate JDBC ダイレクト・モードは Asakusa on M³BP でのみ利用可能です。

コンパイラの設定

WindGate JDBC ダイレクト・モードを利用するには、まずアプリケーションプロジェクトのビルドスクリプト( build.gradle )にこのモードを利用するためのコンパイルオプションを指定します。

以下、 build.gradle の設定例です。

build.gradle

asakusafw {
    m3bp {
        option 'windgate.jdbc.direct', '*'
    }
}

WindGate JDBC ダイレクト・モードに関するコンパイラオプションは以下の通りです。

windgate.jdbc.direct

WindGate JDBC ダイレクト・モードを有効にするプロファイル名のパターン一覧を設定します。

名前のパターンにはワイルドカードとして * を含めることができます。また、複数のパターンを指定する場合にはカンマ (,) 区切りで行います。

コンパイル対象に、このパターンに適合するプロファイル名 1 を持つWindGate JDBCの入出力 が含まれる場合、それらはWindGate JDBC ダイレクト・モード上で動作します。

また、コンパイル対象に上記で指定した以外のプロファイル名を利用しているWindGate JDBCの入出力が含まれる場合、それらは従来のWindGate上で動作します。

既定値: なし (利用しない)

windgate.jdbc.direct.barrier

true を指定した場合、プロファイルごとに入力がすべて完了するまで出力の開始を遅延させます。 false を指定した場合には、これを行いません。

既定値: true (遅延させる)

Warning

この設定に false を設定した場合、（グループ化やソートが含まれない）非常に単純なバッチが高速化されますが、特定の状況でデッドロックが発生する可能性があります。

デッドロックを確実に回避するには、 実行エンジンの設定 で「出力の最大並列実行数」よりも「最大同時接続数」を大きな値に設定する必要があります。

1

バッチアプリケーションが利用するWindGateプロファイルの指定方法などについては、 WindGateユーザーガイド などを参照してください。

JDBCドライバーの配置

WindGate JDBC ダイレクト・モードで使用するJDBCドライバーのライブラリファイルは、 $ASAKUSA_HOME/m3bp/lib ディレクトリ直下に配置してください。

Attention

通常のWindGateとJDBCドライバーファイルの配置ディレクトリが異なることに注意してください。

実行エンジンの設定

WindGate JDBC ダイレクト・モードに関する実行エンジンの設定は以下の通りです。設定方法については上述の 設定方法 を参照してください。

Attention

通常のWindGateはWindGateプロファイル上で動作設定を行いますが、WindGate JDBC ダイレクト・モードではこの設定を利用しません。 Asakusa on M³BPの 設定方法 に従って本項で紹介する項目を設定してください。

com.asakusafw.dag.jdbc.<profile-name>.url

対象のJDBC URLを指定します。

既定値: なし (必須項目)

com.asakusafw.dag.jdbc.<profile-name>.driver

対象のJDBCドライバークラス名を指定します。

既定値: なし (必須項目)

com.asakusafw.dag.jdbc.<profile-name>.properties.<key>

JDBC接続に対して、 <key> で指定した設定を追加します。

Hint

多くのJDBCドライバーでは、 user と password の設定が必要です。

com.asakusafw.dag.jdbc.<profile-name>.connection.max

最大同時接続数を設定します。

既定値: 1

Hint

この接続数を超えて接続を試みた場合、他の接続が解放されるまで待ち合わせます。

com.asakusafw.dag.jdbc.<profile-name>.input.records

JDBC経由でデータを取得する際に、一度に取得する最大行数を設定します。

既定値: 1024

com.asakusafw.dag.jdbc.<profile-name>.output.records

JDBC経由でデータを出力する際に、一度にバッチ処理する最大行数を設定します。

既定値: 1024

com.asakusafw.dag.jdbc.<profile-name>.input.threads

JDBC経由でデータを入力する際の、入力ごとの最大並列実行数を設定します。

現在のバージョンでは、この設定は後述の com.asakusafw.dag.jdbc.<profile-name>.optimizations に ORACLE_PARTITION を設定した場合に有効となる、Oracleのパーティションテーブルに対する並列読み込みを行うにのみ使用します。

Oracleのパーティションテーブルに対する並列読み込みを有効にする場合、この設定値に 1 より大きな値を設定する必要があります。

この設定は Asakusa on M³BPの「ワーカースレッドの最大数 (com.asakusafw.m3bp.thread.max)」以下である必要があります。

既定値: 1

Hint

この値に最大同時接続数より大きな値を設定した場合、いくつかのスレッドは接続の取得を待ち合わせることになります。

com.asakusafw.dag.jdbc.<profile-name>.output.threads

JDBC経由でデータを出力する際の、最大並列実行数を設定します。

この設定は Asakusa on M³BPの「ワーカースレッドの最大数 (com.asakusafw.m3bp.thread.max)」以下である必要があります。

既定値: 1

Hint

この値に最大同時接続数より大きな値を設定した場合、いくつかのスレッドは接続の取得を待ち合わせることになります。

com.asakusafw.dag.jdbc.<profile-name>.output.clear

JDBC経由でデータを出力する際の、事前に出力先を削除する方式を設定します。

利用可能な値:

delete - DELETE 文を利用してテーブルを削除します

truncate - TRUNCATE 文を利用してテーブルを削除します

keep - 削除を行いません

既定値: truncate

Hint

この設定は、DSL側の JdbcExporterDescription.getCustomTruncate() で上書きできます。

com.asakusafw.dag.jdbc.<profile-name>.optimizations

このプロファイルで利用可能な最適化項目の一覧を設定します。

複数の項目を設定する場合、カンマ (,) 区切りで行います。

利用可能な値:

ORACLE_DIRPATH - 出力時にOracleのダイレクトパス・インサートを有効にします

ORACLE_PARTITION - 入力時にOracleのパーティションテーブルに対する並列読み込みを有効にします。

既定値: なし (有効にしない)

Hint

この設定だけでは最適化が有効にならず、 Jdbc{Importer,Exporter}Description.getOptions() でも同名の項目を指定する必要があります。詳しくは WindGateユーザーガイド を参照してください。

Asakusa on M³BPリファレンス

この文書では、Asakusa on M³BPが提供するGradle PluginやDSLコンパイラの設定、およびバッチアプリケーション実行時の設定などについて説明します。

Asakusa on M³BP Gradle Plugin リファレンス

Asakusa on M³BP Gradle Pluginが提供する機能とインターフェースについて個々に解説します。

プラグイン

asakusafw-m3bp

アプリケーションプロジェクトで、Asakusa on M³BPのさまざまな機能を有効にする。

このプラグインは asakusafw-sdk プラグインや asakusafw-organizer プラグインを拡張するように作られているため、それぞれのプラグインも併せて有効にする必要がある（ apply plugin: 'asakusafw-m3bp' だけではほとんどの機能を利用できません）。

タスク

m3bpCompileBatchapps

DSL Compiler for M³BPを利用してDSLをコンパイルする 1 。

asakusafw-sdk プラグインが有効である場合にのみ利用可能。

attachComponentM3bp

デプロイメントアーカイブにAsakusa on M³BP向けのバッチアプリケーションを実行するためのコンポーネントを追加する。

asakusafw-organizer プラグインが有効である場合にのみ利用可能。

asakusafwOrganizer.m3bp.enabled に true が指定されている場合、自動的に有効になる。

attachM3bpBatchapps

デプロイメントアーカイブに m3bpCompileBatchapps でコンパイルした結果を含める。

asakusafw-sdk , asakusafw-organizer の両プラグインがいずれも有効である場合にのみ利用可能。

asakusafwOrganizer.batchapps.enabled に true が指定されている場合、自動的に有効になる。

1

com.asakusafw.gradle.tasks.AsakusaCompileTask [https://docs.asakusafw.com/0.10.3/release/gradle-plugins/com/asakusafw/gradle/tasks/AsakusaCompileTask.html]

タスク拡張

assemble

デプロイメントアーカイブを生成する。

asakusafw-m3bp と asakusafw-organizer プラグインがいずれも有効である場合、 m3bpCompileBatchapps が依存関係に追加される。

compileBatchapp

Asakusa DSLコンパイラを使ってバッチアプリケーションのコンパイルを行い、実行可能モジュールを生成する。

asakusafw-m3bp プラグインが有効である場合、 m3bpCompileBatchapps が依存関係に追加される。

jarBatchapp

compileBatchapp タスクで生成したバッチアプリケーションを含むjarファイルを生成する。

asakusafw-m3bp プラグインが有効である場合、 m3bpCompileBatchapps タスクの生成物がjarファイルの内容に追加される。

規約プロパティ拡張

Batch Application Plugin ( asakusafw ) への拡張

Asakusa on M³BP Gradle PluginはBatch Application Pluginに対してAsakusa on M³BPのビルド設定を行うための規約プロパティを追加します。この規約プロパティは、 asakusafw ブロック内の参照名 m3bp でアクセスできます 2 。

以下、 build.gradle の設定例です。

build.gradle

asakusafw {
    m3bp {
        include 'com.example.batch.*'
        option 'm3bp.native.path', '/usr/bin:/usr/local/bin'
    }
}

この規約オブジェクトは以下のプロパティを持ちます。

m3bp.version

Asakusa on M³BP のコンポーネントバージョンを保持する。

この値は設定による変更は不可。

既定値: Asakusa on M³BP Gradle Pluginが保持する既定のバージョン

m3bp.outputDirectory

コンパイラの出力先を指定する。

文字列や java.io.File などで指定し、相対パスが指定された場合にはプロジェクトからの相対パスとして取り扱う。

既定値: "$buildDir/m3bp-batchapps"

m3bp.include

コンパイルの対象に含めるバッチクラス名のパターンを指定する。

バッチクラス名には * でワイルドカードを含めることが可能。

また、バッチクラス名のリストを指定した場合、それらのパターンのいずれかにマッチしたバッチクラスのみをコンパイルの対象に含める。

既定値: null (すべて)

m3bp.exclude

コンパイルの対象から除外するバッチクラス名のパターンを指定する。

バッチクラス名には * でワイルドカードを含めることが可能。

また、バッチクラス名のリストを指定した場合、それらのパターンのいずれかにマッチしたバッチクラスをコンパイルの対象から除外する。

include と exclude がいずれも指定された場合、 exclude のパターンを優先して取り扱う。

既定値: null (除外しない)

m3bp.runtimeWorkingDirectory

実行時のテンポラリワーキングディレクトリのパスを指定する。

パスにはURIやカレントワーキングディレクトリからの相対パスを指定可能。

未指定の場合、コンパイラの標準設定である「 target/hadoopwork 」を利用する。

既定値: null (コンパイラの標準設定を利用する)

m3bp.option

コンパイラプロパティ （コンパイラのオプション設定）を追加する。

後述する コンパイラプロパティ を <key>, <value> の形式で指定する 3 。

既定値: (Asakusa on M³BP向けのコンパイルに必要な最低限のもの)

m3bp.batchIdPrefix

Asakusa on M³BP向けのバッチアプリケーションに付与するバッチIDの接頭辞を指定する。

文字列を設定すると、それぞれのバッチアプリケーションは「 <接頭辞><本来のバッチID> 」というバッチIDに強制的に変更される。

空文字や null を指定した場合、本来のバッチIDをそのまま利用するが、他のコンパイラが生成したバッチアプリケーションと同じバッチIDのバッチアプリケーションを生成した場合、アプリケーションが正しく動作しなくなる。

既定値: "m3bp."

m3bp.failOnError

Asakusa on M³BP向けのコンパイルを行う際に、コンパイルエラーが発生したら即座にコンパイルを停止するかどうかを選択する。

コンパイルエラーが発生した際に、 true を指定した場合にはコンパイルをすぐに停止し、 false を指定した場合には最後までコンパイルを実施する。

既定値: true (即座にコンパイルを停止する)

2

これらのプロパティは規約オブジェクト com.asakusafw.gradle.plugins.AsakusafwCompilerExtension [https://docs.asakusafw.com/0.10.3/release/gradle-plugins/com/asakusafw/gradle/plugins/AsakusafwCompilerExtension.html] が提供します。

3

コンパイラプロパティを指定する方法は他にいくつかの方法があります。詳しくは com.asakusafw.gradle.plugins.AsakusafwCompilerExtension [https://docs.asakusafw.com/0.10.3/release/gradle-plugins/com/asakusafw/gradle/plugins/AsakusafwCompilerExtension.html] のメソッドの説明を参照してください。

Framework Organizer Plugin ( asakusafwOrganizer ) への拡張

Asakusa on M³BP Gradle Plugin は Framework Organizer Plugin に対してAsakusa on M³BPのビルド設定を行うための規約プロパティを追加します。この規約プロパティは、 asakusafwOrganizer ブロック内の参照名 m3bp でアクセスできます 4 。

この規約オブジェクトは以下のプロパティを持ちます。

m3bp.enabled

デプロイメントアーカイブにAsakusa on M³BPのコンポーネント群を追加するかどうかを指定する。

true を指定した場合にはコンポーネントを追加し、 false を指定した場合には追加しない。

既定値: true (コンポーネント群を追加する)

m3bp.useSystemNativeDependencies

デプロイメントアーカイブのAsakusa on M³BPが、実行環境にインストールされたネイティブの依存ライブラリ群を利用するかどうかを指定する。

true を指定した場合にはインストールされたネイティブの依存ライブラリ群を利用し、 false を指定した場合にはデプロイメントアーカイブにライブラリ群を含めてそちらを利用する。

既定値: false (実行環境にインストールされたネイティブの依存ライブラリ群を利用しない)

Note

この設定に false を指定することで、Asakusa on M³BPが利用する boost などのライブラリをデプロイメントアーカイブに含めることができます。非標準の実行環境の構成を利用している場合や、独自に入手したライブラリを利用したい場合などにはこの設定に true を指定してください。また、それぞれの依存ライブラリのバージョンについては、 $ASAKUSA_HOME/m3bp/native 以下のライブラリに ldd コマンドなどを利用して確認してください。

なお、この設定に false を指定しても全ての依存ライブラリが含まれるわけではありません。詳しくは Asakusa on M3BPユーザーガイド を参照してください。

<profile>.m3bp.enabled

対象のプロファイルに対し、デプロイメントアーカイブにAsakusa on M³BPのコンポーネントを追加するかどうかを指定する。

前述の m3bp.enabled と同様だが、こちらはプロファイルごとに指定できる。

既定値: asakusafwOrganizer.m3bp.enabled (全体のデフォルト値を利用する)

<profile>.m3bp.useSystemNativeDependencies

対象のプロファイルに対し、デプロイメントアーカイブのAsakusa on M³BPが、実行環境にインストールされたネイティブの依存ライブラリ群を利用するかどうかを指定する。

前述の m3bp.useSystemNativeDependencies と同様だが、こちらはプロファイルごとに指定できる。

既定値: asakusafwOrganizer.m3bp.useSystemNativeDependencies (全体のデフォルト値を利用する)

4

これらのプロパティは規約オブジェクト com.asakusafw.m3bp.gradle.plugins.AsakusafwOrganizerM3bpExtension [https://docs.asakusafw.com/asakusa-on-m3bp/0.3.3/release/gradle-plugins/com/asakusafw/m3bp/gradle/plugins/AsakusafwOrganizerM3bpExtension.html] が提供します。

コマンドラインオプション

m3bpCompileBatchapps タスクを指定して gradlew コマンドを実行する際に、 m3bpCompileBatchapps --update <バッチクラス名> と指定することで、指定したバッチクラス名のみをバッチコンパイルすることができます。

また、バッチクラス名の文字列には * をワイルドカードとして使用することもできます。

以下の例では、パッケージ名に com.example.target.batch を含むバッチクラスのみをバッチコンパイルしてデプロイメントアーカイブを作成しています。

./gradlew m3bpCompileBatchapps --update com.example.target.batch.* assemble

そのほか、 m3bpCompileBatchapps タスクは gradlew コマンド実行時に以下のコマンドライン引数を指定することができます。

--options <k1=v1[,k2=v2[,...]]>

追加のコンパイラプロパティを指定する。

規約プロパティ asakusafw.m3bp.option で設定したものと同じキーを指定した場合、それらを上書きする。

--batch-id-prefix <prefix.>

生成するバッチアプリケーションに、指定のバッチID接頭辞を付与する。

規約プロパティ asakusafw.m3bp.batchIdPrefix の設定を上書きする。

--fail-on-error <"true"|"false">

コンパイルエラー発生時に即座にコンパイル処理を停止するかどうか。

規約プロパティ asakusafw.m3bp.failOnError の設定を上書きする。

--update <batch-class-name-pattern>

指定のバッチクラスだけをコンパイルする (指定したもの以外はそのまま残る)。

規約プロパティ asakusafw.m3bp.{in,ex}clude と同様にワイルドカードを利用可能。

このオプションが設定された場合、規約プロパティ asakusafw.m3bp.{in,ex}clude の設定は無視する。

DSL Compiler for M³BPリファレンス

コンパイラプロパティ

DSL Compiler for M³BPで利用可能なコンパイラプロパティについて説明します。これらの設定方法については、 Batch Application Plugin ( asakusafw ) への拡張 の m3bp.option の項を参照してください。

directio.input.filter.enabled

Direct I/O input filterを有効にするかどうか。

true ならば有効にし、 false ならば無効にする。

既定値: true

operator.checkpoint.remove

DSLで指定した @Checkpoint 演算子をすべて除去するかどうか。

true ならば除去し、 false ならば除去しない。

既定値: false

operator.logging.level

DSLで指定した @Logging 演算子のうち、どのレベル以上を表示するか。

debug , info , warn , error のいずれかを指定する。

既定値: info

operator.aggregation.default

DSLで指定した @Summarize , @Fold 演算子の partialAggregate に PartialAggregation.DEFAULT が指定された場合に、どのように集約を行うか。

total であれば部分集約を許さず、 partial であれば部分集約を行う。

既定値: total

input.estimator.tiny

インポーター記述の getDataSize() に DataSize.TINY が指定された際、それを何バイトのデータとして見積もるか。

値にはバイト数か、 +Inf (無限大)、 NaN (不明) のいずれかを指定する。

主に、 @MasterJoin 系の演算子でJOINのアルゴリズムを決める際など、データサイズによる最適化の情報として利用される。

既定値: 10485760 (10MB)

input.estimator.small

インポーター記述の getDataSize() に DataSize.SMALL が指定された際、それを何バイトのデータとして見積もるか。

その他については input.estimator.tiny と同様。

既定値: 209715200 (200MB)

input.estimator.large

インポーター記述の getDataSize() に DataSize.LARGE が指定された際、それを何バイトのデータとして見積もるか。

その他については input.estimator.tiny と同様。

既定値: +Inf (無限大)

operator.join.broadcast.limit

@MasterJoin 系の演算子で、broadcast joinアルゴリズムを利用して結合を行うための、マスタ側の最大入力データサイズ。

基本的には input.estimator.tiny で指定した値の2倍程度にしておくのがよい。

既定値: 20971520 (20MB)

operator.estimator.<演算子注釈名>

指定した演算子の入力に対する出力データサイズの割合。

「演算子注釈名」には演算子注釈の単純名 ( Extract , Fold など) を指定し、値には割合 ( 1.0 , 2.5 など) を指定する。

たとえば、「 operator.estimator.CoGroup 」に 5.0 を指定した場合、すべての @CoGroup 演算子の出力データサイズは、入力データサイズの合計の5倍として見積もられる。

既定値: operator.estimator.* のデフォルト値 を参照

<バッチID>:<オプション名>

指定のオプションを、指定のIDのバッチに対してのみ有効にする。

バッチIDは m3bp. などのプレフィックスが付与する まえの ものを指定する必要がある。

既定値: N/A

dag.planning.option.unifySubplanIo

等価なステージの入出力を一つにまとめる最適化を有効にするかどうか。

true ならば有効にし、 false ならば無効にする。

無効化した場合、ステージの入出力データが増大する場合があるため、特別な理由がなければ有効にするのがよい。

既定値: true

dag.planning.option.checkpointAfterExternalInputs

ジョブフローの入力の直後にチェックポイント処理を行うかどうか。

true ならばチェックポイント処理を行い、 false ならば行わない。

既定値: false

m3bp.native.cmake

アプリケーションのコンパイル時に利用する CMake コマンドの名前またはフルパス。

既定値: cmake

m3bp.native.make

アプリケーションのコンパイル時に利用する Make コマンドの名前またはフルパス。

既定値: make

m3bp.native.path

アプリケーションのコンパイル時に利用する CMake や Make コマンドを探索するためのパス。

複数のディレクトリを指定する場合、パスセパレータ文字 (Unixの場合は ":") で区切って指定する。

既定値: (PATH 環境変数の値)

m3bp.native.cmake.<name>

アプリケーションのコンパイル時に利用する CMake コマンドの追加オプション (-D<name>)。

たとえば、 m3bp.native.cmake.CMAKE_BUILD_TYPE に Debug を指定することで、ビルドタイプを Debug に変更できる。

operator.estimator.* のデフォルト値

operator.estimator.* のデフォルト値

演算子注釈名

計算式

Checkpoint

入力の 1.0 倍

Logging

入力の 1.0 倍

Branch

入力の 1.0 倍

Project

入力の 1.0 倍

Extend

入力の 1.25 倍

Restructure

入力の 1.25 倍

Split

入力の 1.0 倍

Update

入力の 2.0 倍

Convert

入力の 2.0 倍

Summarize

入力の 1.0 倍

Fold

入力の 1.0 倍

MasterJoin

トランザクション入力の 2.0 倍

MasterJoinUpdate

トランザクション入力の 2.0 倍

MasterCheck

トランザクション入力の 1.0 倍

MasterBranch

トランザクション入力の 1.0 倍

Extract

既定値無し

GroupSort

既定値無し

CoGroup

既定値無し

既定値がない演算子に対しては、有効なデータサイズの見積もりを行いません。

互換性について

ここではAsakusa on M³BPを利用する場合に考慮すべき、Asakusa Frameworkやバッチアプリケーションの互換性について説明します。

演算子の互換性

Asakusa on M³BPでは、バッチアプリケーション内の演算子内に定義したstaticフィールドを複数のスレッドから利用する場合があります。このため、演算子クラス内でフィールドにstaticを付与している場合、staticの指定を除去するかフィールド参照がスレッドセーフになるようにしてください。

リリースノート

Attention

Asakusa on M³BP バージョン 0.2.0 以降のリリースノートは以下を参照してください

リリースノート

Release 0.1.3

Dec 05, 2016

このバージョンはバグフィックスのみを含むメンテナンスリリースです。

変更点の詳細は Changelogs を参照してください。

Release 0.1.2

Jul 25, 2016

このバージョンは以下の問題に対応したメンテナンスリリースです。

特定の条件下でDECIMAL型プロパティのソートが正常に動作しない問題を修正

実行時の設定 com.asakusafw.m3bp.output.buffer.size が有効にならない問題を修正

異常終了時のエラーメッセージの出力を改善

その他、細かな機能改善およびバグフィックスが含まれます。

Release 0.1.1

May 10, 2016

このバージョンは以下の問題に対応したメンテナンスリリースです。

コンテナ環境下でCPU情報を正しく取得できない問題を修正

MasterJoin系演算子のマスタ側入力に「空演算子」を指定した際にコンパイルが失敗する問題を修正

グループサイズが大きな場合にクラッシュする問題に対するワークアラウンドを Asakusa on M3BPの最適化設定 に記載

その他、軽微な改善を含みます。

Release 0.1.0

Apr 08, 2016

初版リリース

Changelogs

Attention

Asakusa on M³BP バージョン 0.2.0 以降のChangelogsは以下を参照してください

Changelogs

Release 0.1.3

Dec 05, 2016

[ m3bp milestone:0.1.2 [https://github.com/fixstars/m3bp/issues?&q=milestone:0.1.2] ]

[ asakusafw-dag milestone:0.1.3 [https://github.com/asakusafw/asakusafw-dag/issues?&q=milestone:0.1.3] ]

[ asakusafw-m3bp milestone:0.1.3 [https://github.com/asakusafw/asakusafw-m3bp/issues?&q=milestone:0.1.3] ]

Bundled Components

Component

Version

Asakusa Framework Core

0.8.2 (↑)

Asakusa Framework Language Toolset

0.3.2 (↑)

Asakusa Framework DAG Toolset

0.1.3 (↑)

M³ for Batch Processing

0.1.2

Release 0.1.2

Jul 25, 2016

[ m3bp milestone:0.1.2 [https://github.com/fixstars/m3bp/issues?&q=milestone:0.1.2] ]

[ asakusafw-dag milestone:0.1.2 [https://github.com/asakusafw/asakusafw-dag/issues?&q=milestone:0.1.2] ]

[ asakusafw-m3bp milestone:0.1.2 [https://github.com/asakusafw/asakusafw-m3bp/issues?&q=milestone:0.1.2] ]

Bundled Components

Component

Version

Asakusa Framework Core

0.8.1 (↑)

Asakusa Framework Language Toolset

0.3.1 (↑)

Asakusa Framework DAG Toolset

0.1.2 (↑)

M³ for Batch Processing

0.1.2 (↑)

Release 0.1.1

May 10, 2016

[ m3bp milestone:0.1.1 [https://github.com/fixstars/m3bp/issues?&q=milestone:0.1.1] ]

[ asakusafw-dag milestone:0.1.1 [https://github.com/asakusafw/asakusafw-dag/issues?&q=milestone:0.1.1] ]

[ asakusafw-m3bp milestone:0.1.1 [https://github.com/asakusafw/asakusafw-m3bp/issues?&q=milestone:0.1.1] ]

Bundled Components

Component

Version

Asakusa Framework Core

0.8.0

Asakusa Framework Language Toolset

0.3.0

Asakusa Framework DAG Toolset

0.1.1 (↑)

M³ for Batch Processing

0.1.1 (↑)

Release 0.1.0

Apr 08, 2016

The first release of Asakusa on M³BP.

Bundled Components

Component

Version

Asakusa Framework Core

0.8.0

Asakusa Framework Language Toolset

0.3.0

Asakusa Framework DAG Toolset

0.1.0

M³ for Batch Processing

0.1.0

Asakusa Vanilla

Asakusa Vanillaは、主にアプリケーションのテスト用に設計された、Asakusa Framework実行エンジンのリファレンス実装です。

Asakusa Vanillaは単一ノード上でアプリケーションを実行します。軽量で比較的コンパイル速度が速く、実行時にJVM以外の環境を必要としない、といった特徴を持っているためアプリケーションのテスト - TestDriver で利用する標準の実行エンジンとして採用しています。

ドキュメント

Asakusa Vanilla ユーザーガイド

Asakusa Vanilla リファレンス

リソース

ソースリポジトリ

asakusafw-compiler (GitHub) [https://github.com/asakusafw/asakusafw-compiler]

Asakusa Vanilla ユーザーガイド

この文書では Asakusa Vanilla の利用方法について説明します。

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

Asakusa Framework バージョン 0.10 以降では、標準の設定でAsakusa Vanillaによるテストが有効になっています。

./gradlew check などによってテストドライバを利用したテストを実行すると、Asakusa Vanillaを利用してバッチアプリケーションを実行します。

Attention

Asakusa Framework バージョン 0.9系ではAsakusa Vanillaを有効にするためにビルドスクリプトに対して以下の設定を行う必要がありましたが、バージョン 0.10 以降ではこの定義は不要です。

build.gradle

asakusafw {
    sdk.testkit 'vanilla'
}

なお、バージョン 0.9系、およびそれ以前に標準のテストドライバとして採用していたスモールジョブ実行エンジンを利用するには、ビルドスクリプトに対して以下の設定を行います。ただし、バージョン 0.10 以降ではこの設定によるテスト実行は非推奨です。

build.gradle

asakusafw {
    sdk.testkit 'mapreduce-emulation'
}

Note

Vanillaを利用したDSLのテストでは、 $ASAKUSA_HOME/vanilla/conf/vanilla.properties に記載された設定を利用して Asakusa Vanilla を実行します。このファイルが存在しない場合、すべて既定の設定を利用します。

何らかの設定が必要な場合、該当箇所に設定ファイルを配置してください。設定方法については Asakusa Vanilla リファレンス - 設定項目 を参照してください。

アプリケーションのビルド

Asakusa Vanillaは主にテストドライバ上で利用することを想定していますが、DSLコンパイルによってバッチアプリケーションを生成し、これを実行することも可能です。

Asakusa Vanillaを実行エンジンに利用するバッチアプリケーションを生成するには、ディストリビューションプラグイン 1 を利用したビルドスクリプト ( build.gradle ) に対して以下の設定を追加します。

build.gradle

apply plugin: 'asakusafw-vanilla'

この状態で、Gradleタスク vanillaCompileBatchapps を実行すると、Asakusa Vanilla 向けのバッチアプリケーションのビルドを実行します。

./gradlew vanillaCompileBatchapps

vanillaCompileBatchapps タスクを実行すると、アプリケーションプロジェクトの build/vanilla-batchapps 配下にビルド済みのバッチアプリケーションが生成されます。

標準の設定では、Asakusa Vanillaのバッチアプリケーションは接頭辞に vanilla. が付与されます。例えば、サンプルアプリケーションのバッチID example.summarizeSales の場合、Asakusa VanillaのバッチアプリケーションのバッチIDは vanilla.example.summarizeSales となります。

1

ディストリビューションプラグインについては、 Asakusa Gradle Plugin リファレンス を参照してください。

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

アプリケーションのビルド の設定を行った状態で、Asakusa Frameworkのデプロイメントアーカイブを作成すると、 Asakusa Vanillaのバッチアプリケーションアーカイブを含むデプロイメントアーカイブを生成します。

デプロイメントアーカイブを生成するには Gradleの assemble タスクを実行します。

./gradlew assemble

Note

その他、アプリケーションのデプロイや実行などの方法は他の実行エンジンと同様です。

Asakusa Vanilla リファレンス

この文書では、Asakusa Vanilla が提供するGradle PluginやDSLコンパイラの設定、およびバッチアプリケーション実行時の設定などについて説明します。

Asakusa Vanilla Gradle Plugin リファレンス

Asakusa Vanilla Gradle Pluginが提供する機能とインターフェースについて個々に解説します。

プラグイン

asakusafw-vanilla

アプリケーションプロジェクトで、Asakusa Vanillaのさまざまな機能を有効にする。

このプラグインは asakusafw-sdk プラグインや asakusafw-organizer プラグインを拡張するように作られているため、それぞれのプラグインも併せて有効にする必要がある（ apply plugin: 'asakusafw-vanilla' だけではほとんどの機能を利用できません）。

タスク

vanillaCompileBatchapps

DSL Compiler for Vanillaを利用してDSLをコンパイルする 1 。

asakusafw-sdk プラグインが有効である場合にのみ利用可能。

attachComponentVanilla

デプロイメントアーカイブにAsakusa Vanilla向けのバッチアプリケーションを実行するためのコンポーネントを追加する。

asakusafw-organizer プラグインが有効である場合にのみ利用可能。

asakusafwOrganizer.vanilla.enabled に true が指定されている場合、自動的に有効になる。

attachVanillaBatchapps

デプロイメントアーカイブに vanillaCompileBatchapps でコンパイルした結果を含める。

asakusafw-sdk , asakusafw-organizer の両プラグインがいずれも有効である場合にのみ利用可能。

asakusafwOrganizer.batchapps.enabled に true が指定されている場合、自動的に有効になる。

1

com.asakusafw.gradle.tasks.AsakusaCompileTask [https://docs.asakusafw.com/0.10.3/release/gradle-plugins/com/asakusafw/gradle/tasks/AsakusaCompileTask.html]

タスク拡張

assemble

デプロイメントアーカイブを生成する。

asakusafw-vanilla と asakusafw-organizer プラグインがいずれも有効である場合、 vanillaCompileBatchapps が依存関係に追加される。

compileBatchapp

Asakusa DSLコンパイラを使ってバッチアプリケーションのコンパイルを行い、実行可能モジュールを生成する。

asakusafw-vanilla プラグインが有効である場合、 vanillaCompileBatchapps が依存関係に追加される。

jarBatchapp

compileBatchapp タスクで生成したバッチアプリケーションを含むjarファイルを生成する。

asakusafw-vanilla プラグインが有効である場合、 vanillaCompileBatchapps タスクの生成物がjarファイルの内容に追加される。

規約プロパティ拡張

Batch Application Plugin ( asakusafw ) への拡張

Asakusa Vanilla Gradle PluginはBatch Application Pluginに対してAsakusa Vanillaのビルド設定を行うための規約プロパティを追加します。この規約プロパティは、 asakusafw ブロック内の参照名 vanilla でアクセスできます。

以下、 build.gradle の設定例です。

build.gradle

asakusafw {
    vanilla {
        include 'com.example.batch.*'
    }
}

この規約オブジェクトは以下のプロパティを持ちます。

vanilla.version

Asakusa Vanilla のコンポーネントバージョンを保持する。

この値は設定による変更は不可。

既定値: Asakusa Vanilla Gradle Pluginが保持する既定のバージョン

vanilla.outputDirectory

コンパイラの出力先を指定する。

文字列や java.io.File などで指定し、相対パスが指定された場合にはプロジェクトからの相対パスとして取り扱う。

既定値: "$buildDir/vanilla-batchapps"

vanilla.include

コンパイルの対象に含めるバッチクラス名のパターンを指定する。

バッチクラス名には * でワイルドカードを含めることが可能。

また、バッチクラス名のリストを指定した場合、それらのパターンのいずれかにマッチしたバッチクラスのみをコンパイルの対象に含める。

既定値: null (すべて)

vanilla.exclude

コンパイルの対象から除外するバッチクラス名のパターンを指定する。

バッチクラス名には * でワイルドカードを含めることが可能。

また、バッチクラス名のリストを指定した場合、それらのパターンのいずれかにマッチしたバッチクラスをコンパイルの対象から除外する。

include と exclude がいずれも指定された場合、 exclude のパターンを優先して取り扱う。

既定値: null (除外しない)

vanilla.runtimeWorkingDirectory

実行時のテンポラリワーキングディレクトリのパスを指定する。

パスにはURIやカレントワーキングディレクトリからの相対パスを指定可能。

未指定の場合、コンパイラの標準設定である「 target/hadoopwork 」を利用する。

既定値: null (コンパイラの標準設定を利用する)

vanilla.option

コンパイラプロパティ （コンパイラのオプション設定）を追加する。

後述する コンパイラプロパティ を <key>, <value> の形式で指定する 2 。

既定値: (Asakusa Vanilla向けのコンパイルに必要な最低限のもの)

vanilla.batchIdPrefix

Asakusa Vanilla向けのバッチアプリケーションに付与するバッチIDの接頭辞を指定する。

文字列を設定すると、それぞれのバッチアプリケーションは「 <接頭辞><本来のバッチID> 」というバッチIDに強制的に変更される。

空文字や null を指定した場合、本来のバッチIDをそのまま利用するが、他のコンパイラが生成したバッチアプリケーションと同じバッチIDのバッチアプリケーションを生成した場合、アプリケーションが正しく動作しなくなる。

既定値: "vanilla."

vanilla.failOnError

Asakusa Vanilla向けのコンパイルを行う際に、コンパイルエラーが発生したら即座にコンパイルを停止するかどうかを選択する。

コンパイルエラーが発生した際に、 true を指定した場合にはコンパイルをすぐに停止し、 false を指定した場合には最後までコンパイルを実施する。

既定値: true (即座にコンパイルを停止する)

2

コンパイラプロパティを指定する方法は他にいくつかの方法があります。詳しくは com.asakusafw.gradle.plugins.AsakusafwCompilerExtension [https://docs.asakusafw.com/0.10.3/release/gradle-plugins/com/asakusafw/gradle/plugins/AsakusafwCompilerExtension.html] のメソッドの説明を参照してください。

Framework Organizer Plugin ( asakusafwOrganizer ) への拡張

Asakusa Vanilla Gradle Plugin は Framework Organizer Plugin に対してAsakusa Vanillaのビルド設定を行うための規約プロパティを追加します。この規約プロパティは、 asakusafwOrganizer ブロック内の参照名 vanilla でアクセスできます。

この規約オブジェクトは以下のプロパティを持ちます。

vanilla.enabled

デプロイメントアーカイブにAsakusa Vanillaのコンポーネント群を追加するかどうかを指定する。

true を指定した場合にはコンポーネントを追加し、 false を指定した場合には追加しない。

既定値: true (コンポーネント群を追加する)

<profile>.vanilla.enabled

対象のプロファイルに対し、デプロイメントアーカイブにAsakusa Vanillaのコンポーネントを追加するかどうかを指定する。

前述の vanilla.enabled と同様だが、こちらはプロファイルごとに指定できる。

既定値: asakusafwOrganizer.vanilla.enabled (全体のデフォルト値を利用する)

コマンドラインオプション

vanillaCompileBatchapps タスクを指定して gradlew コマンドを実行する際に、 vanillaCompileBatchapps --update <バッチクラス名> と指定することで、指定したバッチクラス名のみをバッチコンパイルすることができます。

また、バッチクラス名の文字列には * をワイルドカードとして使用することもできます。

以下の例では、パッケージ名に com.example.target.batch を含むバッチクラスのみをバッチコンパイルしてデプロイメントアーカイブを作成しています。

./gradlew vanillaCompileBatchapps --update com.example.target.batch.* assemble

そのほか、 vanillaCompileBatchapps タスクは gradlew コマンド実行時に以下のコマンドライン引数を指定することができます。

--options <k1=v1[,k2=v2[,...]]>

追加のコンパイラプロパティを指定する。

規約プロパティ asakusafw.vanilla.option で設定したものと同じキーを指定した場合、それらを上書きする。

--batch-id-prefix <prefix.>

生成するバッチアプリケーションに、指定のバッチID接頭辞を付与する。

規約プロパティ asakusafw.vanilla.batchIdPrefix の設定を上書きする。

--fail-on-error <"true"|"false">

コンパイルエラー発生時に即座にコンパイル処理を停止するかどうか。

規約プロパティ asakusafw.vanilla.failOnError の設定を上書きする。

--update <batch-class-name-pattern>

指定のバッチクラスだけをコンパイルする (指定したもの以外はそのまま残る)。

規約プロパティ asakusafw.vanilla.{in,ex}clude と同様にワイルドカードを利用可能。

このオプションが設定された場合、規約プロパティ asakusafw.vanilla.{in,ex}clude の設定は無視する。

DSL Compiler for Vanilla リファレンス

コンパイラプロパティ

DSL Compiler for Vanillaで利用可能なコンパイラプロパティについて説明します。これらの設定方法については、 Batch Application Plugin ( asakusafw ) への拡張 の vanilla.option の項を参照してください。

directio.input.filter.enabled

Direct I/O input filterを有効にするかどうか。

true ならば有効にし、 false ならば無効にする。

既定値: true

operator.checkpoint.remove

DSLで指定した @Checkpoint 演算子をすべて除去するかどうか。

true ならば除去し、 false ならば除去しない。

既定値: false

operator.logging.level

DSLで指定した @Logging 演算子のうち、どのレベル以上を表示するか。

debug , info , warn , error のいずれかを指定する。

既定値: info

operator.aggregation.default

DSLで指定した @Summarize , @Fold 演算子の partialAggregate に PartialAggregation.DEFAULT が指定された場合に、どのように集約を行うか。

total であれば部分集約を許さず、 partial であれば部分集約を行う。

既定値: total

input.estimator.tiny

インポーター記述の getDataSize() に DataSize.TINY が指定された際、それを何バイトのデータとして見積もるか。

値にはバイト数か、 +Inf (無限大)、 NaN (不明) のいずれかを指定する。

主に、 @MasterJoin 系の演算子でJOINのアルゴリズムを決める際など、データサイズによる最適化の情報として利用される。

既定値: 10485760 (10MB)

input.estimator.small

インポーター記述の getDataSize() に DataSize.SMALL が指定された際、それを何バイトのデータとして見積もるか。

その他については input.estimator.tiny と同様。

既定値: 209715200 (200MB)

input.estimator.large

インポーター記述の getDataSize() に DataSize.LARGE が指定された際、それを何バイトのデータとして見積もるか。

その他については input.estimator.tiny と同様。

既定値: +Inf (無限大)

operator.join.broadcast.limit

@MasterJoin 系の演算子で、broadcast joinアルゴリズムを利用して結合を行うための、マスタ側の最大入力データサイズ。

基本的には input.estimator.tiny で指定した値の2倍程度にしておくのがよい。

既定値: 20971520 (20MB)

operator.estimator.<演算子注釈名>

指定した演算子の入力に対する出力データサイズの割合。

「演算子注釈名」には演算子注釈の単純名 ( Extract , Fold など) を指定し、値には割合 ( 1.0 , 2.5 など) を指定する。

たとえば、「 operator.estimator.CoGroup 」に 5.0 を指定した場合、すべての @CoGroup 演算子の出力データサイズは、入力データサイズの合計の5倍として見積もられる。

既定値: operator.estimator.* のデフォルト値 を参照

<バッチID>:<オプション名>

指定のオプションを、指定のIDのバッチに対してのみ有効にする。

バッチIDは vanilla. などのプレフィックスが付与する まえの ものを指定する必要がある。

既定値: N/A

dag.planning.option.unifySubplanIo

等価なステージの入出力を一つにまとめる最適化を有効にするかどうか。

true ならば有効にし、 false ならば無効にする。

無効化した場合、ステージの入出力データが増大する場合があるため、特別な理由がなければ有効にするのがよい。

既定値: true

dag.planning.option.checkpointAfterExternalInputs

ジョブフローの入力の直後にチェックポイント処理を行うかどうか。

true ならばチェックポイント処理を行い、 false ならば行わない。

既定値: false

operator.estimator.* のデフォルト値

operator.estimator.* のデフォルト値

演算子注釈名

計算式

Checkpoint

入力の 1.0 倍

Logging

入力の 1.0 倍

Branch

入力の 1.0 倍

Project

入力の 1.0 倍

Extend

入力の 1.25 倍

Restructure

入力の 1.25 倍

Split

入力の 1.0 倍

Update

入力の 2.0 倍

Convert

入力の 2.0 倍

Summarize

入力の 1.0 倍

Fold

入力の 1.0 倍

MasterJoin

トランザクション入力の 2.0 倍

MasterJoinUpdate

トランザクション入力の 2.0 倍

MasterCheck

トランザクション入力の 1.0 倍

MasterBranch

トランザクション入力の 1.0 倍

Extract

既定値無し

GroupSort

既定値無し

CoGroup

既定値無し

既定値がない演算子に対しては、有効なデータサイズの見積もりを行いません。

実行時の設定

Asakusa Vanillaのバッチアプリケーション実行時の設定は、 設定ファイル を使う方法と 環境変数 を使う方法があります。

設定ファイル

Asakusa Vanillaに関するバッチアプリケーション実行時のパラメータは、 $ASAKUSA_HOME/vanilla/conf/vanilla.properties に記述します。このファイルは、 Asakusa Vanilla ユーザーガイド - デプロイメントアーカイブの作成 の設定を行った状態でデプロイメントアーカイブを作成した場合にのみ含まれています。

このファイルに設定した内容はAsakusa Vanillaのバッチアプリケーションの設定として使用され、バッチアプリケーション実行時の動作に影響を与えます。

環境変数

Asakusa Vanillaに関するバッチアプリケーション実行時のパラメータは、環境変数 ASAKUSA_VANILLA_ARGS に設定することもできます。

環境変数 ASAKUSA_VANILLA_ARGS の値には --engine-conf <key>=<value> という形式でパラメータを設定します。

設定ファイルと環境変数で同じプロパティが設定されていた場合、環境変数の設定値が利用されます。

設定項目

Asakusa Vanillaのバッチアプリケーション実行時の設定項目は以下の通りです。

com.asakusafw.vanilla.thread.max

タスクを実行するワーカースレッドの最大数を設定します。

既定値: 1

com.asakusafw.vanilla.partitions

scatter-gather操作(シャッフル操作)のパーティション数を設定します。

既定値: (ワーカースレッドの最大数)

Hint

Asakusa Vanillaの現在の実装では、パーティション数をワーカースレッド数よりも大きな値にするメリットはほとんどありません。

com.asakusafw.vanilla.pool.size

エンジン内で利用可能な入出力バッファーの合計サイズを設定します。

この値を超えるバッファーを利用しようとした場合、古いバッファーをファイルシステム上に書き出します。

既定値: 268435456 ( 256MB )

Hint

Asakusa Vanillaでは上記のバッファーをJVMのヒープ外に確保します。そのため、Java VMの設定でヒープサイズの上限を指定しても、それとは 別に バッファー用のメモリを消費します。

com.asakusafw.vanilla.pool.swap

古いバッファーをファイルシステム上に待避する際のファイルシステムパスを設定します。

指定したパスの配下に一時ディレクトリを作成し、そこにバッファーファイルを作成します。

既定値: (システムの一時ディレクトリー)

com.asakusafw.vanilla.pool.compression

古いバッファーをファイルシステム上に待避する際の、ファイルの圧縮形式を指定します。

以下のいずれかの値を指定可能です。

com.asakusafw.vanilla.core.io.BufferedByteChannelDecorator

ファイルを圧縮せず、入出力のバッファリングのみを行います。

com.asakusafw.vanilla.core.io.NullByteChannelDecorator

ファイルを圧縮せず、入出力のバッファリングも行いません。

com.asakusafw.vanilla.client.util.SnappyByteChannelDecorator

ファイルをSnappy形式で圧縮します。

com.asakusafw.vanilla.client.util.Lz4ByteChannelDecorator

ファイルをLZ4形式で圧縮します。

LZ4形式を利用する場合、LZ4ライブラリ lz4-java [https://github.com/lz4/lz4-java] をVanilla実行環境のクラスパスに配置する必要があります。以下、lz4-java [https://github.com/lz4/lz4-java] を含めたデプロイメントアーカイブを生成する build.gradle の設定例です。

build.gradle

configurations {
    lz4
}
dependencies {
    lz4 group: 'org.lz4', name: 'lz4-java', version: '1.5.1'
}
asakusafwOrganizer {
    assembly.into('vanilla/lib') {
        put configurations.lz4
    }
}

既定値: com.asakusafw.vanilla.core.io.BufferedByteChannelDecorator

com.asakusafw.vanilla.output.buffer.size

出力バッファーあたりのバイト数を設定します。

各出力が、この値から後述の「出力バッファのマージン値」を引いた値( com.asakusafw.vanilla.output.buffer.size - com.asakusafw.vanilla.output.buffer.margin )を超えた場合、次のバッファーを新たに確保して出力を続行します。

既定値: 4194304 ( 4MB )

Hint

古いバッファーをファイルシステム上に待避する際、各ファイルのサイズはおよそここで指定したサイズ以下になります。

com.asakusafw.vanilla.output.buffer.margin

出力バッファーのマージンとなるバイト数を設定します。

この値は実行時に取り扱う最大レコードサイズよりも大きな値を設定すべきです。

また、この値は com.asakusafw.vanilla.output.buffer.size の1/2より小さい値を設定してください。最大レコードサイズが大きいことでこれが満たせない場合、 com.asakusafw.vanilla.output.buffer.size の値を調整してください。

既定値: 1048576 ( 1MB )

com.asakusafw.vanilla.output.record.size

レコードサイズの推定平均バイト数を設定します。

この値は、出力バッファー当たりの最大レコード数を算出するために利用します。

既定値: 64

Hint

この値を大きくしすぎると、出力バッファーサイズを大きくしてもバッファー当たりのレコード数がすぐに上限に達してしまい、バッファーを有効活用できなくなります。また、この値を小さくしすぎると、出力バッファーごとのレコード管理のためのメタデータが大きくなりすぎてしまいます。

出力バッファーサイズに極端に大きな値を指定する場合や、消費メモリー量を細かく制御したい場合を除き、この設定を変更する必要はありません。

com.asakusafw.vanilla.merge.threshold

各スレッド毎の、scatter-gather操作でマージ処理を行う際の入力チャンク数を指定します。

入力チャンク数がこの値を超過する場合、この値と後述の com.asakusafw.vanilla.merge.factor の値に従い、入力チャンクに対して段階的にマージ処理を行います。

既定値: 0 （段階的マージを無効とし、すべての入力チャンクを一度にマージする）

com.asakusafw.vanilla.merge.factor

上記 com.asakusafw.vanilla.merge.threshold の設定に従って段階的マージを行う際に、マージ処理の対象となるファイル数を決定する係数を設定します。

マージが実行される際には com.asakusafw.vanilla.merge.threshold * com.asakusafw.vanilla.merge.factor で算出されたファイル数を一度にマージします。

既定値: 0.75

com.asakusafw.dag.input.file.directory

演算子リファレンス - 巨大な入力グループへの対応 などを利用してメモリ上のバッファをファイルとして退避する際に使用する、ファイルの出力先ディレクトリを設定します。

既定値: なし (未指定の場合、JVMのシステムプロパティ java.io.tmpdir で設定されているディレクトリを利用)

Attention

大量のバッファが出力されるような処理を実行する場合には、出力先に十分な空き領域を確保する必要があることに注意してください。

hadoop.<name>

指定の <name> を名前に持つHadoopの設定を追加します。

Hint

Asakusa Vanillaでは、一部の機能 (Direct I/Oなど) にHadoopのライブラリ群を利用しています。このライブラリ群がHadoopの設定を参照している場合、この項目を利用して設定値を変更できます。

Asakusa全体に関するHadoopの設定は $ASAKUSA_HOME/core/conf/asakusa-resources.xml 内で行えますが、 同一の項目に対する設定が asakusa-resources.xml と hadoop.<name> の両方に存在する場合、後者の設定値を優先します。

Java VMの設定

Asakusa Vanillaでバッチアプリケーションを実行する際には、Java VMをひとつ起動してそのプロセス内でAsakusaの演算子を実行します。

このとき、対象のJava VMを起動する際のオプション引数を、環境変数 ASAKUSA_VANILLA_OPTS で指定できます。

以下は環境変数の設定例です。

export ASAKUSA_VANILLA_OPTS='-Xmx16g'

実行コマンドの設定

Asakusa Vanilla実行用のJVMプロセスを起動するJavaコマンドは、環境変数 JAVA_CMD で設定することができます。 JAVA_CMD が未設定の場合、 PATH 環境変数に含まれる java コマンドが使用されます。

Framework Organizer Plugin ( asakusafwOrganizer ) への拡張 で vanilla.useSystemHadoop が true になっている場合、 Asakusa Vanilla実行用のJVMプロセスを起動するコマンドには hadoop コマンドが使用され、このコマンドは環境変数 HADOOP_CMD で設定することができます。 HADOOP_CMD が未設定の場合、 PATH 環境変数に含まれる hadoop コマンドが使用されます。

環境変数 ASAKUSA_VANILLA_LAUNCHER は実行コマンドの先頭に任意のコマンド文字列を追加します。

Tip

バッチアプリケーション実行時の環境変数は、YAESSプロファイルで設定することも可能です。

Asakusa Vanillaを利用する場合、コマンドラインジョブのプロファイル command.vanilla が利用できます。 $ASAKUSA_HOME/yaess/conf/yaess.properties に command.vanilla.env.HADOOP_CMD といったような設定を追加することで、YAESSからAsakusa Vanillaを実行する際に環境変数が設定されます。

YAESSのコマンドラインジョブの設定方法について詳しくは、 YAESSユーザーガイド - コマンドラインジョブの実行 などを参照してください。

ログの設定

Asakusa Vanillaの実行時のログ設定は、Logback設定ファイル $ASAKUSA_HOME/vanilla/conf/logback.xml で設定します。

WindGate JDBC ダイレクト・モード

Asakusa on M³BP 向けの機能として提供しているWindGate JDBC ダイレクト・モードはAsakusa Vanillaからも利用することができます。

WindGate JDBC ダイレクト・モードを利用するには、アプリケーションプロジェクトのビルドスクリプト( build.gradle )にこのモードを利用するためのコンパイルオプションを指定します。

以下、 build.gradle の設定例です。

build.gradle

asakusafw {
    vanilla {
        option 'windgate.jdbc.direct', '*'
    }
}

WindGate JDBC ダイレクト・モードの利用方法などについては、Asakusa on M³BP の以下のドキュメントを参照してください。

Asakusa on M3BPの最適化設定 - WindGate JDBC ダイレクト・モード

Asakusa on MapReduce

Asakusa on MapReduceは、Asakusa DSLを始めとするAsakusa Frameworkの開発基盤を利用して作成したバッチアプリケーションに対して、MapReduceをその実行基盤として利用するための機能セットを提供します。

Deprecated

Asakusa Framework バージョン 0.10.0 以降、Asakusa on MapReduce、および本書からリンクするAsakusa on MapReduce関連機能は非推奨機能となりました。詳しくは、バージョン 0.10.0 の リリースノート を参照してください。

ドキュメント

Asakusa on MapReduce リファレンス

エミュレーションモードによるアプリケーションテスト

Asakusa on MapReduce DSLの可視化

開発環境にHadoopを導入する

MapReduceタスクの最適化設定

ライブラリキャッシュの設定

ソースリポジトリ

asakusafw-mapreduce (GitHub) [https://github.com/asakusafw/asakusafw-mapreduce]

リンク

Apache Hadoop [https://hadoop.apache.org/]

Asakusa on MapReduce リファレンス

この文書では、Asakusa on MapReduceが提供するGradle PluginやDSLコンパイラの設定、およびバッチアプリケーション実行時の設定などについて説明します。

Asakusa on MapReduce Gradle Plugin リファレンス

Asakusa on MapReduce Gradle Pluginが提供する機能とインターフェースについて個々に解説します。

プラグイン

asakusafw-mapreduce

アプリケーションプロジェクトで、Asakusa on MapReduceのさまざまな機能を有効にする 1 。

このプラグインは asakusafw-sdk プラグインや asakusafw-organizer プラグインを拡張するように作られているため、それぞれのプラグインも併せて有効にする必要がある（ apply plugin: 'asakusafw-mapreduce' だけではほとんどの機能を利用できません）。

1

com.asakusafw.mapreduce.gradle.plugins.AsakusafwMapReducePlugin [https://docs.asakusafw.com/0.10.3/release/gradle-plugins/com/asakusafw/mapreduce/gradle/plugins/AsakusafwMapReducePlugin.html]

タスク

mapreduceCompileBatchapps

Asakusa DSL Compiler for MapReduceを利用してDSLをコンパイルする 2 。

asakusafw-sdk プラグインが有効である場合にのみ利用可能。

attachComponentMapReduce

デプロイメントアーカイブにMapReduce向けのバッチアプリケーションを実行するためのコンポーネントを追加する。

asakusafw-organizer プラグインが有効である場合にのみ利用可能。

asakusafwOrganizer.mapreduce.enabled に true が指定されている場合、自動的に有効になる。

attachMapReduceBatchapps

デプロイメントアーカイブに mapreduceCompileBatchapps でコンパイルした結果を含める。

asakusafw-sdk , asakusafw-organizer の両プラグインがいずれも有効である場合にのみ利用可能。

asakusafwOrganizer.batchapps.enabled に true が指定されている場合、自動的に有効になる。

2

com.asakusafw.gradle.tasks.AsakusaCompileTask [https://docs.asakusafw.com/0.10.3/release/gradle-plugins/com/asakusafw/gradle/tasks/AsakusaCompileTask.html]

タスク拡張

assemble

デプロイメントアーカイブを生成する。

asakusafw-mapreduce と asakusafw-organizer プラグインがいずれも有効である場合、 mapreduceCompileBatchapps が依存関係に追加される。

compileBatchapp

Asakusa DSLコンパイラを使ってバッチアプリケーションのコンパイルを行い、実行可能モジュールを生成する。

asakusafw-mapreduce プラグインが有効である場合、 mapreduceCompileBatchapps が依存関係に追加される。

jarBatchapp

compileBatchapp タスクで生成したバッチアプリケーションを含むjarファイルを生成する。

asakusafw-mapreduce プラグインが有効である場合、 mapreduceCompileBatchapps タスクの生成物がjarファイルの内容に追加される。

規約プロパティ拡張

Batch Application Plugin ( asakusafw ) への拡張

Asakusa on MapReduce Gradle Pluginは Batch Application Plugin に対して Asakusa on MapReduceのビルド設定を行うための規約プロパティを追加します。この規約プロパティは、 asakusafw ブロック内の参照名 mapreduce でアクセスできます 3 。

以下、 build.gradle の設定例です。

build.gradle

asakusafw {
    mapreduce {
        include 'com.example.batch.*'
        option 'hashJoinForTiny', 'false'
    }

この規約オブジェクトは以下のプロパティを持ちます。

mapreduce.version

Asakusa on MapReduceのコンポーネントバージョンを保持する。

この値は設定による変更は不可。

既定値: Asakusa on MapReduce Gradle Pluginが保持する既定のバージョン

mapreduce.outputDirectory

コンパイラの出力先を指定する。

文字列や java.io.File などで指定し、相対パスが指定された場合にはプロジェクトからの相対パスとして取り扱う。

既定値: "$buildDir/batchc"

mapreduce.include

コンパイルの対象に含めるバッチクラス名のパターンを指定する。

バッチクラス名には * でワイルドカードを含めることが可能。

また、バッチクラス名のリストを指定した場合、それらのパターンのいずれかにマッチしたバッチクラスのみをコンパイルの対象に含める。

既定値: null (すべて)

mapreduce.exclude

コンパイルの対象から除外するバッチクラス名のパターンを指定する。

バッチクラス名には * でワイルドカードを含めることが可能。

また、バッチクラス名のリストを指定した場合、それらのパターンのいずれかにマッチしたバッチクラスをコンパイルの対象から除外する。

include と exclude がいずれも指定された場合、 exclude のパターンを優先して取り扱う。

既定値: null (除外しない)

mapreduce.runtimeWorkingDirectory

実行時のテンポラリワーキングディレクトリのパスを指定する。

パスにはURIやカレントワーキングディレクトリからの相対パスを指定可能。

未指定の場合、コンパイラの標準設定である「 target/hadoopwork 」を利用する。

既定値: null (コンパイラの標準設定を利用する)

mapreduce.option

コンパイラプロパティ （コンパイラのオプション設定）を追加する。

後述する コンパイラプロパティ を <key>, <value> の形式で指定する 4 。

既定値: (MapReduce向けのコンパイルに必要な最低限のもの)

mapreduce.failOnError

MapReduce向けのコンパイルを行う際に、コンパイルエラーが発生したら即座にコンパイルを停止するかどうかを選択する。

コンパイルエラーが発生した際に、 true を指定した場合にはコンパイルをすぐに停止し、 false を指定した場合には最後までコンパイルを実施する。

既定値: true (即座にコンパイルを停止する)

3

これらのプロパティは規約オブジェクト com.asakusafw.gradle.plugins.AsakusafwCompilerExtension [https://docs.asakusafw.com/0.10.3/release/gradle-plugins/com/asakusafw/gradle/plugins/AsakusafwCompilerExtension.html] が提供します。

4

コンパイラプロパティを指定する方法は他にいくつかの方法があります。詳しくは com.asakusafw.gradle.plugins.AsakusafwCompilerExtension [https://docs.asakusafw.com/0.10.3/release/gradle-plugins/com/asakusafw/gradle/plugins/AsakusafwCompilerExtension.html] のメソッドの説明を参照してください。

Framework Organizer Plugin ( asakusafwOrganizer ) への拡張

Asakusa on MapReduce Gradle Plugin は Framework Organizer Plugin に対して Asakusa on MapReduceのビルド設定を行うための規約プロパティを追加します。この規約プロパティは、 asakusafwOrganizer ブロック内の参照名 mapreduce でアクセスできます 5 。

この規約オブジェクトは以下のプロパティを持ちます。

mapreduce.enabled

デプロイメントアーカイブにMapReduce向けのバッチアプリケーションを実行するためのコンポーネントを追加するかどうかを指定する (各プロファイルのデフォルト値)。

true を指定した場合にはコンポーネントを追加し、 false を指定した場合には追加しない。

既定値: true (コンポーネントを追加する)

<profile>.mapreduce.enabled

対象のプロファイルに対し、デプロイメントアーカイブにMapReduce向けのバッチアプリケーションを実行するためのコンポーネントを追加するかどうかを指定する。

前述の mapreduce.enabled と同様だが、こちらはプロファイルごとに指定できる。

既定値: asakusafwOrganizer.mapreduce.enabled (全体のデフォルト値を利用する)

5

これらのプロパティは規約オブジェクト com.asakusafw.mapreduce.gradle.plugins.AsakusafwOrganizerMapReduceExtension [https://docs.asakusafw.com/0.10.3/release/gradle-plugins/com/asakusafw/mapreduce/gradle/plugins/AsakusafwOrganizerMapReduceExtension.html] が提供します。

コマンドラインオプション

mapreduceCompileBatchapps タスクを指定して gradlew コマンドを実行する際に、 mapreduceCompileBatchapps --update <バッチクラス名> と指定することで、指定したバッチクラス名のみをバッチコンパイルすることができます。

また、バッチクラス名の文字列には * をワイルドカードとして使用することもできます。

以下の例では、パッケージ名に com.example.target.batch を含むバッチクラスのみをバッチコンパイルしてデプロイメントアーカイブを作成しています。

./gradlew mapreduceCompileBatchapps --update com.example.target.batch.* assemble

そのほか、 mapreduceCompileBatchapps タスクは gradlew コマンド実行時に以下のコマンドライン引数を指定することができます。

--options <k1=v1[,k2=v2[,...]]>

追加のコンパイラプロパティを指定する。

規約プロパティ asakusafw.mapreduce.option で設定したものと同じキーを指定した場合、それらを上書きする。

--fail-on-error <"true"|"false">

コンパイルエラー発生時に即座にコンパイル処理を停止するかどうか。

規約プロパティ asakusafw.mapreduce.failOnError の設定を上書きする。

--update <batch-class-name-pattern>

指定のバッチクラスだけをコンパイルする (指定したもの以外はそのまま残る)。

規約プロパティ asakusafw.mapreduce.{in,ex}clude と同様にワイルドカードを利用可能。

このオプションが設定された場合、規約プロパティ asakusafw.mapreduce.{in,ex}clude の設定は無視する。

Asakusa DSL Compiler for MapReduce リファレンス

コンパイラプロパティ

Asakusa DSL Compiler for MapReduceで利用可能なコンパイラプロパティについて説明します。これらの設定方法については、 Batch Application Plugin ( asakusafw ) への拡張 の mapreduce.option の項を参照してください。

Asakusa DSL Compiler for MapReduce - コンパイルオプション

項目名

既定値

概要

enableCombiner

無効

部分集約 6 の既定値。

部分集約を許す演算子に対して PartialAggregation.DEFAULT が 7 指定された場合に、このオプションが有効であれば部分集約を行い、そうでなければ行わない。

compressFlowPart

有効

ステージ数が少なくなる方法でフロー演算子を展開する。

このオプションが無効であればフロー演算子の展開時に全ての入出力にチェックポイント演算子を挿入する。このオプションが有効であれば、展開時に何も挿入しない。

compressConcurrentStage

有効

互いに影響のないステージを1つのステージに合成する。

このオプションが有効であれば、互いに依存関係のない2つ以上のステージを単一のステージに合成し、無効であれば合成しない。

hashJoinForTiny

有効

データサイズに DataSize.TINY と指定したジョブフローの入力をマスタとして結合する際に、可能であればハッシュ表での結合を行う。

このオプションが有効であれば上記の動作を行い、無効であればコンパイラが自動的に結合戦略を決定する。

hashJoinForSmall

無効

将来の拡張のためにリザーブされた項目。現在は動作に影響しない。

enableDebugLogging

無効

Logging.Level.DEBUG が指定されたロギング演算子を利用可能にする。

このオプションが有効であれば、そのようなロギング演算子をコンパイル後も保持する。無効であれば、コンパイル時にそれらの演算子を除去する。

上記の他に、 X から始まるいくつかの コンパイラスイッチ も存在します。コンパイラスイッチもコンパイルオプションと同じシステムプロパティを利用します。

Note

compressFlowPart の既定値は0.2から「有効」に変更しました。チェックポイント演算子はMapReduceの単位 (ステージ) に区切りをいれる演算子で、元は「フロー部品のテスト時とできるだけ同じ構造にしたほうが良い」という前提でこのオプションを無効化していました。しかし、あまりにMapReduceの回数が増えてしまい、処理効率が著しく低下するため、0.2よりこの規定値が見直されることになりました。

Note

compressConcurrentStage は利点と欠点のある最適化です。この最適化により、ステージ数は最小で「クリティカルパスのステージ数」まで低下します。しかし、ここで合成されるステージは本来互いに影響がありませんので、Hadoopはこれらのステージを同時に処理することが可能です。

この最適化の欠点は、時間のかかるステージとかからないステージを合成してしまうと、後者のステージが本来先に終わる場合でも、前者のステージの処理が完了するまで余計な待ち合わせが発生してしまう点です。 Hadoopクラスターが十分に大きく、ワークフローエンジンが並列のジョブ投入をサポートしている場合は、このオプションは見直すべきでしょう。

Note

hashJoinForTiny は、Hadoopの DistributedCache の仕組みを利用しています。ハッシュ表での結合を行う場合、入力データをHadoopクラスターの全てのノードに配布します。そこでハッシュ表を構築し、タスクのメモリ上に保持します。

現在の標準的な結合戦略はShuffle+Sortを利用したマージ結合であるため、これは結合操作を行うたびにReduceフェーズが必要になってしまいます。結果としてMapReduceのステージ数が増大してしまいますが、ハッシュ表を利用する場合には全てのノードのメモリ上に表を構築しているため、Reduce処理が不要になり、ステージ数を削減できるという利点があります。

ただし、およそハッシュ表の元になったデータサイズの倍程度のメモリを必要とするため、適用範囲が限られてしまうという問題はあります。

6

部分集約の設定については、 演算子リファレンス の単純集計演算子や畳み込み演算子を参照してください。

7

com.asakusafw.vocabulary.flow.processor.PartialAggregation [https://docs.asakusafw.com/0.10.3/release/api/com/asakusafw/vocabulary/flow/processor/PartialAggregation.html]

コンパイラスイッチ

コンパイラスイッチはコンパイラの内部的な挙動を操作するためのオプションで、 コンパイラプロパティ と同様の方法で設定します。

Hint

通常の場合、コンパイラスイッチを指定する必要はありません。コンパイル時にコンパイラから推奨される場合がありますので、その際に利用を検討してください。

すべてのコンパイラスイッチは X<項目名>=<値> の形式で設定します。以下は変更可能なコンパイラスイッチの一覧です。

コンパイラスイッチの項目

項目名

既定値

概要

MAPREDUCE-370

DISABLED

利用中のHadoopにパッチ MAPREDUCE-370 が適用済みかどうか。 ENABLED の場合は適用済みと仮定し、 DISABLED の場合は未適用と仮定する。

compressFlowBlockGroup

ENABLED

コンパイラプロパティ の compressConcurrentStage を適用した際、ステージ内のMapperとReducerを併合するかどうか。 ENABLED の場合は併合し、 DISABLED の場合は併合しない。

packaging

ENABLED

アプリケーションのパッケージングを行うかどうか。

javaVersion

1.8 8

DSLコンパイラがコンパイル時に指定するJavaのバージョン

Tip

コンパイルオプションは項目名を間違えた場合にエラーとなりますが、コンパイラスイッチは項目名を間違えると単に設定が無視されます。

8

Asakusa Gradle Plugin ユーザーガイド に従ってアプリケーションプロジェクトを作成した場合は、Gradle Pluginの設定値が適用されます。詳しくは Asakusa Gradle Plugin リファレンス を参照してください。

エミュレーションモードによるアプリケーションテスト

この文書では、エミュレーションモードを利用したアプリケーションのテストについて説明します。

エミュレーションモード

エミュレーションモードを有効にしてAsakusa DSLのテストを実行すると、Asakusa Frameworkが提供するラッパー機構を利用してHadoopの処理を実行します。

エミュレーションモードではテストを実行しているプロセス内でほとんどの処理を行うため、デバッグモードのブレークポイントなどを利用できるようになります。

Attention

本機能はアプリケーションプロジェクトのHadoopライブラリを利用するため、標準で設定されたものと異なるHadoopディストリビューションやバージョンを利用する際に、正しく動かない可能性があります。

Hint

エミュレーションモードを有効にしていない場合、テスト実行時にコマンドラインインターフェースを利用して、別プロセスで様々な処理を行います。

別プロセスで動作させたほうが Java VM 上の問題は起こりにくくなるため、エミュレーションモード利用時に正しく動かない場合には、本機能を無効化して動作を確認してみることを推奨します。

Hint

エミュレーションモードを使用することで、Windows環境でテストドライバーを使ったテストの実行が可能となります。

Windows環境でエミュレーションモードを使った開発環境の設定例については、 Asakusa Framework スタートガイド for Windows を参照してください。

フローDSL/バッチDSLのテスト

エミュレーションモードを有効にして データフローのテスト を行うと、IDEからブレークポイントを指定してデータフロー内の演算子メソッドの動作を確認したり、カバレッジツールと連携して演算子メソッドのテストカバレッジを確認しやすくなります。

インテグレーションテスト

バッチテストランナー とエミュレーションモードを併用すると、インテグレーションテスト時のデバッグ作業がやりやすくなります。

エミュレーションモードの利用方法

Asakusa Framework バージョン 0.8.0 以降では、Asakusa Framework スタートガイド や Asakusa Gradle Plugin ユーザーガイド などで説明しているプロジェクトテンプレートを利用する場合、標準でエミュレーションモードが利用されます。

エミュレーションモードの設定

アプリケーションプロジェクトでエミュレーションモードの設定を変更する場合は、ビルドスクリプトの asakusafw ブロック内の sdk.testkit の値を変更します。

以下は、エミュレーションモードを利用を明示的に設定する例です。この設定は Asakusa Gradle Plugin ユーザーガイド を利用する標準の構成と同じ設定です。

build.gradle

asakusafw {
    sdk.testkit 'mapreduce-emulation'
}

エミュレーションモードの設定を無効化し、環境のHadoopを利用するには以下のように設定します。

build.gradle

asakusafw {
    sdk.testkit 'mapreduce'
}

Attention

通常はエミュレーションモードの利用を推奨しています。エミュレーションモードが正常に動作しないなどの場合にのみ、この設定変更を検討してください。

Tip

エミュレーションモードを有効する別の方法として、ビルドスクリプトにはモジュール設定を記述せず、 Shafu [https://docs.asakusafw.com/jinrikisha/ja/html/shafu.html] の機能を使ってEclipse上で設定する方法があります。この方法で設定を行うと、Eclipse上でのみエミュレーションモードが有効になります。詳しくは Shafu [https://docs.asakusafw.com/jinrikisha/ja/html/shafu.html] の「設定」の説明を参照してください。

Gradle上でのテストドライバー実行

エミュレーションモードの設定 を有効化した状態でGradleの test タスクを実行すると、テストドライバーがエミュレーションモードで実行されます。

Tip

エミュレーションモードを有効にして Gradle上でテストを実行すると、Gradleが提供する JaCoCo Plugin [http://www.gradle.org/docs/current/userguide/jacoco_plugin.html] などのソースコードカバレッジ取得機能との連携が可能になります。

Attention

Asakusa Framework バージョン 0.10.3 において、Windows上でエミュレーションモードを有効してテストドライバーを実行した際に以下のようなエラーログが出力されることがありますが、動作上は問題ありません。

INFO  インプロセステスト実行用の機能をテストドライバーにインストールしています
INFO  インプロセステスト実行用の最適化設定をテストドライバーにインストールしています
ERROR Failed to locate the winutils binary in the hadoop binary path
java.io.IOException: Could not locate executable null\bin\winutils.exe in the Hadoop binaries.
    at org.apache.hadoop.util.Shell.getQualifiedBinPath(Shell.java:356) [hadoop-common-2.7.2.jar:na]
    ...

Eclipse上でのテストドライバー実行

エミュレーションモードの設定 を有効化した状態でGradleの eclipse タスクを実行すると、Eclipse上でアプリケーションプロジェクトに対してエミュレーションモードが有効になります。

この状態でEclipseからテストドライバーを利用するテストクラスやバッチテストランナーを実行すると、テストドライバーがエミュレーションモードで実行されます。

Tip

エミュレーションモードを有効にすると、テストドライバーを使ったテストクラスのデバッグ実行時にEclipseのブレークポイント機能などを利用できます。

実行モードの選択

Attention

通常の場合、ここで説明する設定は不要です。旧バージョンからのマイグレーション後にエミュレーションモードが正常に動作しない場合にのみ、ここで説明する設定を有効にして動作を確認してください。

標準の設定では、 com.asakusafw.sdk:asakusa-sdk-test-emulation を指定したエミュレーションモードの実行時にはスモールジョブ実行エンジンが使用されます。

エミュレーションモードをスモールジョブ実行エンジンを使用しない設定で実行するには、テストドライバー実行時に以下のシステムプロパティを設定します。

asakusa.testdriver.configurator.inprocess.optimize

true: エミュレーションモードでスモールジョブ実行エンジンを使用する(デフォルト)

false: エミュレーションモードでスモールジョブ実行エンジンを使用しない

Attention

Asakusa Framework バージョン 0.7.2 以前では com.asakusafw:asakusa-test-inprocess を指定したエミュレーションモードの実行にはスモールジョブ実行エンジンは使用されませんでしたが、バージョン 0.7.3 からはスモールジョブ実行エンジンを使用するよう変更されました。

See also

スモールジョブ実行エンジンについては、 MapReduceタスクの最適化設定 を参照してください。

Asakusa on MapReduce DSLの可視化

この文書では、Asakusa DSLの分析を行うにあたって、Asakusa on MapReudceが提供するDSLの可視化の仕組みについて解説します。

Attention

本書で説明する機能はMapReduce DSLコンパイラでのみ使用可能です。

Asakusa DSLの分析用ファイル

Asakusa DSLをバッチコンパイルして生成したバッチアプリケーションアーカイブファイル 1 には、Asakusa DSLの分析用ファイルが含まれています。この分析用ファイルは、バッチアプリケーションの構造を把握したり、アプリケーション実行時に発生した問題箇所の特定を行うことを補助します。

分析用ファイルは、バッチアプリケーションアーカイブファイル内の <バッチID>/opt/dsl-analysis ディレクトリ配下に配置されています 2 。各分析用ファイルの説明を以下に示します。なお、以下に示すファイルのうち、dotファイルについては後述の Graphvizによるグラフの生成 を参照してグラフ形式として出力することも可能です。

dotスクリプトファイル一覧

ファイル名

説明

batch/compiled-structure.txt

バッチコンパイルした結果のバッチ構造を示すテキストファイル

batch/compiled-structure.dot

バッチコンパイルした結果のバッチ構造を示すdotファイル

batch/compiled-merged-structure.dot

バッチコンパイルした結果のバッチ構造を示すdotファイル。同一の演算子を単一のノードとして表現する。

batch/original-structure.txt

バッチコンパイル前のバッチ構造を示すテキストファイル

batch/original-structure.dot

バッチコンパイル前のバッチ構造を示すdotファイル

batch/original-merged-structure.txt

バッチコンパイル前のバッチ構造を示すテキストファイル。同一の演算子を単一のノードとして表現する。

jobflow/<フローID>/flowgraph.dot

フローの入出力を示すdotファイル

jobflow/<フローID>/stagegraph.dot

ステージ全体の構造を示すdotファイル

jobflow/<フローID>/stageblock-XX.dot

各ステージ単位の構造を示すdotファイル

1

バッチアプリケーションアーカイブファイルを生成する方法については、 Asakusa Gradle Plugin ユーザーガイド を参照してください。

2

バッチアプリケーションアーカイブファイルから分析用ファイルを取り出すには、jarコマンド等を使用してアーカイブファイルから分析用ファイルを抽出してください。なお、プロジェクトをバッチコンパイルした環境では、プロジェクトのビルドディレクトリ配下の batchc/<バッチID>/opt/dsl-analysis ディレクトリに分析用ファイルが出力されています。

Graphvizによるグラフの生成

グラフ生成ツールである Graphviz 3 を使用して、dotファイルからグラフファイルを生成する方法を説明します。

3

http://www.graphviz.org/

Graphvizのインストール

開発環境にGraphvizをインストールします。UbuntuにGraphvizをインストールする例を以下に示します。

sudo apt-get install graphviz

Graphvizの詳細やインストール方法は上記のGraphvizのサイト等を参照して下さい。

dotスクリプトからグラフファイルを作成する

Graphvizを使って、dotファイルからPDF形式 4 でグラフを作成する例を以下に示します。

# バッチアプリケーションアーカイブファイルを解凍する
jar -xf example-app-batchapps-1.0-SNAPSHOT.jar
# バッチアプリケーションアーカイブに含まれるdotファイルをPDFに変換する
cd example.summarizeSales/opt/dsl-analysis/jobflow/byCategory
dot -Tpdf -o stagegraph.pdf stagegraph.dot

4

GraphvizではPDF形式の他に、 PNGやJPEG形式など様々な形式でグラフを出力することができます。詳しくは Graphviz のマニュアルなどを参照してください。

グラフの出力例

分析用ファイルから生成することができるグラフの出力例を紹介します。

ステージグラフ

jobflow/<フローID>/stagegraph.dot は、ジョブフローが持つステージ 5 全体の構造を示すグラフを提供します。

ステージ全体の構造のうち、特定のステージのみのグラフを参照したい場合は、 jobflow/<フローID>/stageblock-XX.dot を参照します。

5

ステージとはAsakusa DSLをバッチコンパイルした結果生成されるバッチアプリケーションに含まれるMapReduceジョブの単位です。詳しくは Asakusa DSLユーザーガイド - Batch DSLコンパイラが生成するバッチアプリケーション などを参照してください。

フローグラフ

jobflow/<フローID>/flowgraph.dot は、ジョブフローの入出力、及びジョブフローに含まれる演算子間の入出力の関係を示すグラフを提供します。

バッチ構造を示すテキストファイルの出力例

分析用ファイルに含まれるバッチ構造を示すテキストファイルの例を紹介します。

バッチコンパイル前のバッチ構造

batch/original-structure.txt はバッチコンパイル前のバッチ構造を示します 6 。

batch: example.summarizeSales
flow: byCategory
    input:
        salesDetail (hoge.jobflow.SalesDetailFromCsv)
        itemInfo (hoge.jobflow.ItemInfoFromCsv)
        storeInfo (hoge.jobflow.StoreInfoFromCsv)
    output:
        categorySummary (hoge.jobflow.CategorySummaryToCsv)
        errorRecord (hoge.jobflow.ErrorRecordToCsv)
    flow: hoge.jobflow.CategorySummaryJob
        operator: hoge.operator.CategorySummaryOperator#setErrorMessage([class hoge.modelgen.dmdl.model.ErrorRecord, class java.lang.String])[message[class java.lang.String]=店舗不明]
        input: InputDescription{name=itemInfo, type=class hoge.modelgen.dmdl.model.ItemInfo}
        output: OutputDescription{name=errorRecord, type=class hoge.modelgen.dmdl.model.ErrorRecord}
        input: InputDescription{name=salesDetail, type=class hoge.modelgen.dmdl.model.SalesDetail}
        output: OutputDescription{name=categorySummary, type=class hoge.modelgen.dmdl.model.CategorySummary}
        input: InputDescription{name=storeInfo, type=class hoge.modelgen.dmdl.model.StoreInfo}
        operator: com.asakusafw.vocabulary.flow.util.CoreOperatorFactory$Restructure#toString([])[]
        operator: com.asakusafw.vocabulary.flow.util.CoreOperatorFactory$Restructure#toString([])[]
        operator: hoge.operator.CategorySummaryOperator#summarizeByCategory([class hoge.modelgen.dmdl.model.JoinedSalesInfo])[]
        operator: hoge.operator.CategorySummaryOperator#checkStore([class hoge.modelgen.dmdl.model.StoreInfo, class hoge.modelgen.dmdl.model.SalesDetail])[]
...

6

バッチコンパイル前のバッチ構造はdotファイルによるグラフ形式も利用することができますが、テキストファイル形式のほうがより詳細な情報が含まれています。

バッチコンパイル後のバッチ構造

batch/compiled-structure.txt はバッチコンパイル後のバッチ構造を示します 7 。

batch: example.summarizeSales
flow: byCategory
    input:
        salesDetail (hoge.jobflow.SalesDetailFromCsv)
        itemInfo (hoge.jobflow.ItemInfoFromCsv)
        storeInfo (hoge.jobflow.StoreInfoFromCsv)
    output:
        categorySummary (hoge.jobflow.CategorySummaryToCsv)
        errorRecord (hoge.jobflow.ErrorRecordToCsv)
    stages:
        prologue:
        main:
            stage: hoge.batchapp.example.summarizeSales.byCategory.stage0001.StageClient
                mapper: hoge.batchapp.example.summarizeSales.byCategory.stage0001.StageMapper1
                    fragment: hoge.batchapp.example.summarizeSales.byCategory.stage0001.MapFragment1
                mapper: hoge.batchapp.example.summarizeSales.byCategory.stage0001.StageMapper2
                    fragment: hoge.batchapp.example.summarizeSales.byCategory.stage0001.MapFragment2
                        operator: hoge.operator.CategorySummaryOperator#checkStore([class hoge.modelgen.dmdl.model.StoreInfo, class hoge.modelgen.dmdl.model.SalesDetail])[]
                            side-data: storeInfo (hoge.jobflow.StoreInfoFromCsv)
                reducer: hoge.batchapp.example.summarizeSales.byCategory.stage0001.StageReducer
                    fragment: hoge.batchapp.example.summarizeSales.byCategory.stage0001.ReduceFragment4
                        operator: hoge.operator.CategorySummaryOperator#joinItemInfo([class hoge.modelgen.dmdl.model.ItemInfo, class hoge.modelgen.dmdl.model.SalesDetail])[]
                    fragment: hoge.batchapp.example.summarizeSales.byCategory.stage0001.MapFragment3
                        operator: com.asakusafw.vocabulary.flow.util.CoreOperatorFactory$Restructure#toString([])[]
                        operator: hoge.operator.CategorySummaryOperator#setErrorMessage([class hoge.modelgen.dmdl.model.ErrorRecord, class java.lang.String])[message[class java.lang.String]=商品不明]
            stage: hoge.batchapp.example.summarizeSales.byCategory.stage0002.StageClient
                mapper: hoge.batchapp.example.summarizeSales.byCategory.stage0002.StageMapper1
                    fragment: hoge.batchapp.example.summarizeSales.byCategory.stage0002.MapFragment1
                        operator: hoge.operator.CategorySummaryOperator#checkStore([class hoge.modelgen.dmdl.model.StoreInfo, class hoge.modelgen.dmdl.model.SalesDetail])[]
                            side-data: storeInfo (hoge.jobflow.StoreInfoFromCsv)
                    fragment: hoge.batchapp.example.summarizeSales.byCategory.stage0002.MapFragment2
                        operator: com.asakusafw.vocabulary.flow.util.CoreOperatorFactory$Restructure#toString([])[]
                        operator: hoge.operator.CategorySummaryOperator#setErrorMessage([class hoge.modelgen.dmdl.model.ErrorRecord, class java.lang.String])[message[class java.lang.String]=店舗不明]
            stage: hoge.batchapp.example.summarizeSales.byCategory.stage0003.StageClient
                mapper: hoge.batchapp.example.summarizeSales.byCategory.stage0003.StageMapper1
...

7

バッチコンパイル後のバッチ構造はdotファイルによるグラフ形式も利用することができますが、テキストファイル形式のほうがより詳細な情報が含まれています。

開発環境にHadoopを導入する

この文書は、Asakusa Frameworkのバッチアプリケーション開発環境で利用するHadoopのインストールやセットアップに関して説明します。

See also

運用環境(Hadoopクラスター)で利用するHadoopの導入に関しては、 Asakusa Framework デプロイメントガイド を参照してください。

開発環境で利用するHadoopについて

開発環境で利用するHadoopは、おもにバッチアプリケーションをテスト実行する目的で使用します。また、開発環境でYAESSを使ったバッチアプリケーションの実行を確認する場合に使用します。開発環境では、Hadoopを「スタンドアロンモード」と呼ばれる分散処理を行わず単一JVM上で実行するモードで利用することを想定しています。

なおテストの実行に関して、Asakusa FrameworkではHadoopジョブを実行せずにバッチアプリケーションのテストを実行するための「エミュレーションモード」を提供しています。エミュレーションモードを利用する場合、開発環境に対するHadoopの設定は不要です。また多くの場合、Hadoopのスタンドアロンモードよりも高速にテストを実行することができます。

エミュレーションモードの利用方法については、 エミュレーションモードによるアプリケーションテスト を参照してください。

Hadoopディストリビューションとバージョン

Asakusa Framework バージョン 0.10.3 では、開発環境で利用するHadoopは Apache Hadoop [http://hadoop.apache.org/] 2系の安定バージョン( 2.x.x )を推奨しています 1 。

Attention

Asakusa Framework バージョン 0.8.0 から、Hadoop1系 ( 1.x.x ) は非対応となりました。

開発環境で Apache Hadoop [http://hadoop.apache.org/] 以外のHadoopディストリビューションを利用する場合、一部の機能が利用できなかったり、開発環境に追加の設定が必要な場合があります 2 。

なお、運用環境で利用するHadoopのディストリビューションは、 Apache Hadoop [http://hadoop.apache.org/] 以外の様々なHadoopディストリビューションを利用できます。

See also

Asakusa Frameworkが動作検証を行なっているHadoopディストリビューションについては、 対応プラットフォーム を参照してください。

1

Apache Hadooop のリリースバージョンについては、Apache Hadoop の ドキュメント Hadoop Releases [http://hadoop.apache.org/releases.html] などを参照してください。

2

例えば、Mapが提供するMapRFSを操作するためには、MapRFS操作用のライブラリが必要となります。

開発環境向けのHadoopのセットアップ

ここでは、開発環境のHadoopのセットアップ方法について説明します。

Apache Hadoopのインストール

Apache Hadoopのダウンロードページ [http://hadoop.apache.org/releases.html#Download] からHadoop本体のコンポーネントのtarball hadoop-2.X.X.tar.gz ( X はバージョン番号 ) をダウンロードします。

ダウンロードが完了したら、以下の例を参考にしてApache Hadoopをインストールします。

cd ~/Downloads
tar xf hadoop-*.tar.gz
sudo chown -R root:root hadoop-*/
sudo mv hadoop-*/ /usr/lib
sudo ln -s /usr/lib/hadoop-* /usr/lib/hadoop

環境変数の設定

Asakusa Frameworkを通じてHadoopを実行する場合、実行する hadoop コマンドの配置場所を環境変数を利用して指定する必要があります。

hadoop コマンドを利用するAsakusa Frameworkの各コンポーネントは、次の手順で hadoop コマンドを検索します。

環境変数 HADOOP_CMD が設定されている場合、 $HADOOP_CMD を hadoop コマンドとみなして利用する

(非推奨) 環境変数 HADOOP_HOME にHadoopのインストール先が指定されている場合、 $HADOOP_HOME/bin/hadoop を利用する

hadoop コマンドのパス ( 環境変数 PATH ) が通っている場合、それを利用する

以下は、環境変数 HADOOP_CMD の設定例です。

export HADOOP_CMD=/usr/lib/hadoop/bin/hadoop

また、テスト実行の際には上記で検出したHadoopの設定とは異なる設定でテストを実行することも可能です。テストドライバーが利用するHadoopの設定は次の順番で検出しています。

環境変数 HADOOP_CONF が指定されている場合、その内容を設定ディレクトリへのパスとして利用する

hadoop コマンドを実行し、そこで利用されている設定ディレクトリを利用する

上記のうち、環境変数 HADOOP_CONF を指定する際には core-site.xml などのHadoopの設定情報が格納されたディレクトリへのパスを指定してください。

MapReduceタスクの最適化設定

この文書では、Hadoopパラメータとして設定可能なMapReduceタスクの最適化設定について説明します。

Attention

本書で説明する機能はAsakusa on MapReduceでのみ使用可能です。

See also

Hadoopパラメータの設定方法については、 Hadoopパラメータの設定 を参照してください。

タスク最適化の設定

MapReduceタスクの最適化に関する設定を有効にするには、後述する最適化設定用のHadoopパラメータを asakusa-resources.xml に設定します。

以下はタスク最適化の設定例です。

asakusa-resources.xml

<property>
    <name>com.asakusafw.inprocess.limit</name>
    <value>5242880</value>
</property>
<property>
    <name>com.asakusafw.input.combine.max</name>
    <value>256</value>
</property>
<property>
    <name>com.asakusafw.input.combine.tiny.limit</name>
    <value>1048576</value>
</property>
<property>
    <name>com.asakusafw.reducer.tiny.limit</name>
    <value>1048576</value>
</property>

この例では以下の設定を行なっています。

スモールジョブ実行エンジン に関する設定

スモールジョブ実行エンジンを有効にする最大入力バイト数: 5MB

入力スプリットの結合 に関する設定

Mapperごとの最大スプリット数: 256

「小さな入力」として扱う最大バイト数: 1MB

Reduceタスクの調整 に関する設定

「小さなジョブ」として扱う最大バイト数: 1MB

スモールジョブ実行エンジン

スモールジョブ実行エンジンはAsakusa Frameworkの実行モジュールとして提供される、小さなデータの処理に適したジョブの実行エンジンです。

これを従来のHadoopが提供するMapReduceフレームワークと組み合わせて利用することで、幅広いデータレンジに対してそれぞれ適した実行エンジンを自動的に選択し、効果的にバッチアプリケーションを実行することができます。

スモールジョブ実行エンジンに関するHadoopパラメータは以下の通りです。

スモールジョブ実行エンジン

設定名

既定値

概要

com.asakusafw.inprocess.limit

-1

スモールジョブ実行エンジンを有効にする最大入力バイト数 1 ( 0 未満の場合は無効)

com.asakusafw.mapreduce.shuffle.buffer

67108864

スモールジョブ実行エンジン内で利用する、シャッフルバッファ向けのメモリバイト数 2

com.asakusafw.mapreduce.shuffle.tempdir

java.io.tmpdir と同等

スモールジョブ実行エンジンが使用する一時ディレクトリ 3

1

スモールジョブ実行エンジンの選択を判定する際に使用される入力データのバイト数は、該当ジョブが入力とする全てのファイルサイズの合計値です。

2

通常はこのパラメータを変更する必要はありません。

3

一時ディレクトリを指定する場合は必ずフルパスで指定してください。

Attention

スモールジョブ実行エンジンは、ジョブを実行するクライアントプロセス内で処理を行うため、大きなデータを処理した際に性能が大幅に劣化します。通常の場合、 com.asakusafw.inprocess.limit は最大でも10MB程度 ( 10485760 ) を上限値とすることを推奨します。

Attention

入力データが小さくても計算に時間が掛かる処理や、途中でデータを大量に増幅させる処理などが存在する場合、本機能を有効にすることで余計に処理時間を要する可能性があります。

Attention

スモールジョブ実行エンジンを利用して処理を行った場合、Hadoopが提供するジョブ履歴の機能や、ログの保存機能などは利用できません。これらHadoopの機能を利用したい場合には、上記の設定は行わないでください。なお、スモールジョブ実行エンジンはHadoopクライアントのログ設定を利用してログを出力します。

入力スプリットの結合

Asakusa Frameworkでは、MapReduceジョブを実行する際に複数の入力データのスプリットを結合して、実行するMapタスク数を減らす機能を提供しています。

入力スプリットの結合に関するHadoopパラメータは以下の通りです。

入力スプリットの結合

設定名

既定値

概要

com.asakusafw.input.combine.max

Integer.MAX_VALUE

Mapperごとの最大スプリット数

com.asakusafw.input.combine.tiny.limit

-1

「小さな入力」として扱う最大バイト数 ( 0 未満の場合は無効)

Hint

Mapタスク数を減らすことで計算リソースの無駄遣いを抑制したり、タスク起動のオーバーヘッドを削減したりできます。

Mapperごとの最大スプリット数

com.asakusafw.input.combine.max は Mapperごとの最大スプリット数 の設定です。

特定のMapperの入力データのスプリット数がこの設定値を超える場合、そのMapperに対する入力スプリットをこの設定値となるよう結合します。ジョブの中で複数のMapperが利用される場合、最大で Mapper数 * Mapperごとの最大スプリット数 のMapタスクが実行されます。

Hint

この設定値は通常、はMapタスクの合計スロット数の1~2倍程度が妥当でしょう。標準では Integer.MAX_VALUE に設定されているため、この機能は無効化されています。

Tip

スタンドアロンモードのHadoop、およびスモールジョブ実行エンジン上では、 Mapperごとの最大スプリット数 は自動的に 1 が設定されます。

遺伝的アルゴリズムの調整

入力スプリットの結合には遺伝的アルゴリズムを利用します。遺伝的アルゴリズムのパラメータは以下の設定が可能です。

遺伝的アルゴリズムの調整

設定名

既定値

概要

com.asakusafw.input.combine.ga.generation

100

世代数 4

com.asakusafw.input.combine.ga.population

50

世代ごとの個体数 5

com.asakusafw.input.combine.ga.mutation

0.001

突然変異率 6

com.asakusafw.input.combine.ga.initialLoacality

0.8

初期遺伝子に対するデータローカルタスクの割合 7

com.asakusafw.input.combine.ga.averageTimeWeight

1.0

タスクの平均実行時間に対する重み付け 8

com.asakusafw.input.combine.ga.nonLocalPenalty

2.0

非データローカルタスクのペナルティ率 9

Note

基本的に、上記パラメータの変更は不要です。例外的に、遺伝的アルゴリズムによる計算にかかる時間が気になる場合、世代数や個体数を減らすことで計算時間を削減できます。

4

遺伝的アルゴリズムの世代数を表します。この値を増やすことによってより最適解に近いスケジュールを発見できるようになりますが、遺伝的アルゴリズムの処理時間は世代数に対して線形に増加します。

5

遺伝的アルゴリズムの世代ごとの個体数を表します。世代数と同様にスケジュールが改善する可能性がありますが、アルゴリズムの処理時間は線形に増加します。

6

遺伝的アルゴリズムの突然変異率を表します。この値は各個体に含まれる遺伝子上の要素に対する発生確率を表しています。この値を高くすると、アルゴリズムはランダム探索に近づいていきます。逆にこの値を低くすると、アルゴリズムは局所解に陥りやすくなるおそれがあります。

7

アルゴリズムで利用する初期遺伝子に対する、データローカリティの割合を表します。この値を低く設定した場合、遺伝子の多様性が保たれる反面、最適解を得るためには十分な世代数(generation)が必要となります。この値を高く設定した場合、初期状態でよい結果が得られる可能性が高い反面、遺伝子の多様性が低下するため局所解に陥る可能性があります。

8

ジョブに含まれるタスクの最悪実行時間に対し、タスクの平均実行時間をどの程度重視するかを表します。 1.0の場合には同等として扱います。この値を小さく設定すると、アルゴリズムはタスクごとの最悪時間を最小にすることを優先します。この値を大きく設定すると、タスク全体のデータローカリティの向上を優先します。

9

tmpfsを利用したり、ラックネットワークが極端に遅いなど、ローカルストレージとネットワーク速度に大きな開きがある場合、この値を大きな値に変更します。アルゴリズムでは、この値を利用してデータローカリティのないデータの読み出し速度を計算します。具体的には、データローカリティのあるデータ処理に掛かる推定時間に対し、この値を乗算した値をデータローカリティのないデータ処理に掛かる推定時間として利用します。

「小さな入力」として扱う最大バイト数

com.asakusafw.input.combine.tiny.limit は 「小さな入力」として扱う最大バイト数 の設定です。

特定のMapperへの入力データサイズがこの設定値よりも小さな場合、そのMapperに対するスプリットはすべて1つにまとめられます。

Attention

この設定値に大きな数を指定した場合、 Mapタスクが分散処理を行えなくなる場合があります。

Hint

標準では -1 に設定されているため、この設定は無効化されています。この設定値には非常に小さな値を指定するか、設定を無効化しておくことを推奨します。

Reduceタスクの調整

Asakusa Frameworkでは、MapReduceジョブを実行する際に入力データの特性に応じてReduceタスクを調整する機能を提供しています。

Reduceタスクの調整に関するHadoopパラメータは以下の通りです。

Reduceタスクの調整

設定名

既定値

概要

com.asakusafw.reducer.tiny.limit

-1

「小さなジョブ」として扱う最大バイト数 ( 0 未満の場合は無効)

Hint

Reduceタスク数を減らすことで計算リソースの無駄遣いを抑制したり、タスク起動のオーバーヘッドを削減したりできます。

「小さなジョブ」として扱う最大バイト数

com.asakusafw.reducer.tiny.limit は 「小さな入力」として扱う最大バイト数 の設定です。

あるジョブの入力データサイズが、「小さなジョブ」として扱う最大バイト数以下の場合に、そのジョブのReduceタスク数を 1 に再設定します（Reduceタスクを利用しない場合を除く）。

Attention

入力データが小さくても計算に時間が掛かる処理や、Mapタスク内でデータを大量に増幅させる処理などが存在する場合、この設定を有効にすることで余計に処理時間を要する可能性があります。

Hint

ここには非常に小さな値（数MB程度）を指定するか、本機能を無効化しておくことを推奨します。標準では -1 に設定されているため、この設定は無効化されています。

ライブラリキャッシュの設定

この文書では、Hadoopパラメータとして設定可能なライブラリキャッシュの設定方法について説明します。

Attention

本書で説明する機能はAsakusa on MapReduceでのみ使用可能です。

See also

Hadoopパラメータの設定方法については、 Hadoopパラメータの設定 を参照してください。

概要

Asakusa Frameworkを利用してアプリケーションを実行する場合、フレームワークやバッチアプリケーションのライブラリをHadoop上にアップロードして利用します。

この処理はバッチに含まれるジョブ(ステージ)ごとに行うため、多くのジョブが含まれるバッチを実行すると、アップロードやスレーブノードへの展開に時間がかかるため、処理全体が遅くなってしまいます。

アプリケーションライブラリのキャッシュを利用すると、過去にアップロードしたライブラリをキャッシュして再利用するようになり、実行時ライブラリの配布を高速化します。

Tip

特に Direct I/O Hive が使用する実行ライブラリはファイルサイズが大きいため、Hadoopジョブの実行のつどHadoopクラスターにライブラリを配布することでパフォーマンスに悪影響を与える可能性があります。このため、ライブラリキャッシュの設定を行いHive連携モジュール用のライブラリをキャッシュすることを推奨します。

キャッシュパスの設定

ライブラリキャッシュを有効にするには、Hadoopパラメータ com.asakusafw.launcher.cache.path にキャッシュファイルを保持するHadoopファイルシステムのパスを指定します。

以下はライブラリキャッシュの設定例です。

asakusa-resources.xml

<property>
    <name>com.asakusafw.launcher.cache.path</name>
    <value>target/libcache</value>
</property>

ライブラリキャッシュの設定を追加した状態でYAESSからアプリケーションを実行した後にキャッシュパスの内容を参照すると、アプリケーション実行時のライブラリファイルがキャッシュされていることが確認できます。

$ hadoop fs -ls target/libcache/*
-rw-------   3 asakusa asakusa     507053 2014-06-23 13:11 /user/asakusa/target/libcache/1b1eded1/asakusa-runtime-all.jar
-rw-------   3 asakusa asakusa          8 2014-06-23 13:11 /user/asakusa/target/libcache/1b1eded1/asakusa-runtime-all.jar.acrc
-rw-------   3 asakusa asakusa     129107 2014-06-23 13:11 /user/asakusa/target/libcache/b27b4dc4/jobflow-byCategory.jar
-rw-------   3 asakusa asakusa          8 2014-06-23 13:11 /user/asakusa/target/libcache/b27b4dc4/jobflow-byCategory.jar.acrc

Attention

運用環境のHadoopクラスターを複数のAsakusa Frameworkの構成から利用するような場合、その構成間でキャッシュパスが重複しているとキャッシュファイルの競合が起こりキャッシュが不正な状態となる可能性があります。このような場合、複数の構成それぞれに異なるキャッシュパスを設定するのがよいでしょう。

その他の設定

ライブラリキャッシュの設定により、キャッシュの動作を詳細に設定することができます。

ライブラリキャッシュの設定項目の一覧を以下に示します。

ライブラリキャッシュの設定

設定名

既定値

概要

com.asakusafw.launcher.cache.path

未指定

キャッシュファイルを保持するHadoopファイルシステムのパス

com.asakusafw.launcher.cache.retry.max

50

キャッシュ操作に対する最大リトライ回数 1

com.asakusafw.launcher.cache.retry.interval

100

キャッシュ操作に対するリトライインターバル(ミリ秒)

com.asakusafw.launcher.cache.local

JVMのテンポラリディレクトリ 2

キャッシュ処理が利用するローカルテンポラリディレクトリ

com.asakusafw.launcher.cache.threads

4

キャッシュの検証や作成に利用するスレッド数

com.asakusafw.launcher.cache.jobjar

true

アプリケーションJarをHadoopに登録するかどうか 3

1

キャッシュ操作に失敗した場合は、キャッシュを利用しない状態でアプリケーションが実行されます。

2

JVMのシステムプロパティ java.io.tmp で設定されるディレクトリ配下に asakusa-launcher-cache-<ユーザー名> というディレクトリを作成し、これを利用します。

3

Hadoopディストリビューションによっては、この設定項目が true の状態ではアプリケーションが実行できません。ライブラリキャッシュの設定後アプリケーション実行がエラー終了する場合は、この設定項目を変更してみてください。

キャッシュされたライブラリのクリーンアップ

不要になったキャッシュファイルを削除する場合、アプリケーションが実行していない状態でキャッシュパス上のファイル、またはキャッシュパス全体を削除します。

Hint

ライブラリファイルをキャッシュする際に、ローカルファイルシステムの同じパス上のファイルは、常にHadoopでも同一のパス上に配置されます。ほとんどの場合、通常の利用方法ではキャッシュされたライブラリが占めるHadoop上のディスク容量を気にする必要はありません

プロダクトについて

Asakusa Frameworkのプロダクト情報に関するドキュメントです。

対応プラットフォーム

試験的機能

非推奨機能

ライセンス

対応プラットフォーム

Hadoopディストリビューション

Asakusa Framework は、以下のHadoopディストリビューションと組み合わせた運用環境で動作を検証しています。

動作検証プラットフォーム(Hadoopディストリビューション)

Distribution

Version

OS

Hortonworks Data Platform

2.6.5

CentOS 7.4

MapR

5.2.2 1

CentOS 7.3

CDH

5.13.0 2

CentOS 7.2

Amazon EMR

5.24.0

Amazon Linux 2018.03 based

Microsoft Azure HDInsight

3.6

Ubuntu 16.04.3

1

MapReduce Version 1 (MRv1) には対応していません。

2

MapReduce Version 1 (MRv1) には対応していません。

アプリケーション開発環境

Asakusa Frameworkを利用したバッチアプリケーションの開発環境は、 以下のプラットフォームで動作を検証しています。

動作検証プラットフォーム(開発環境)

種類

Product

Version

OS

Ubuntu Desktop

16.04.3

OS

Windows

10 (1809)

OS

MacOSX 3

10.13

Java

JDK 4 5

1.8.0_201

ビルドツール

Gradle 6

4.7

IDE

Eclipse IDE for Java Developers

2019-03

IDE

IntelliJ IDEA Community Edition 7

2017.2.6

3

MacOSX上では基本的な動作のみ検証しています。

4

JREでは一部の機能が動作しません。必ずJDKを使用してください。

5

開発環境に対するJavaのセットアップについては、 開発環境のJava を参照してください。

6

Gradleの利用については、 Asakusa Gradle Plugin ユーザーガイド を参照してください。

7

IntelliJ IDEAの利用は試験的機能として提供しています。詳しくは IntelliJ IDEAの利用 を参照してください。

WindGate

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

動作検証プラットフォーム(WindGate/JDBC 8 )

種類

Product

Version

DBMS

PostgreSQL

9.3

JDBC Driver

PostgreSQL JDBC Driver

9.1 Build 901

8

データベースを利用しない場合(例えば WindGate/CSV のみを使う場合)には不要です

リンク

対応プラットフォームのリンク集です。

Product

Link

Apache Hadoop

http://hadoop.apache.org/

Hortonworks Data Platform

http://hortonworks.com/hdp/

MapR

http://www.mapr.com/

Cloudera CDH

http://www.cloudera.com/content/cloudera/en/products-and-services/cdh.html

Amazon EMR

http://aws.amazon.com/elasticmapreduce/

Microsoft Azure HDInsight

https://azure.microsoft.com/services/hdinsight/

CentOS

http://www.centos.org/

Ubuntu

http://www.ubuntu.com/

Windows

http://windows.microsoft.com/

MacOSX

http://www.apple.com/osx/

JDK (Java SE)

http://www.oracle.com/technetwork/java/javase/index.html

Gradle

http://www.gradle.org/

Eclipse

http://www.eclipse.org/

IntelliJ IDEA

https://www.jetbrains.com/idea/

PostgreSQL

http://www.postgresql.org/

試験的機能

試験的機能とは、以下のいずれかに該当するような状態で公開している機能です。

十分な検証が行われていない

限られたプラットフォーム上でのみ動作する

暫定仕様の状態で公開されているため、将来大きな仕様変更が行われる可能性がある

ドキュメントが未作成または十分ではない

試験的機能の多くはAsakusa Frameworkの将来バージョンで正式機能に昇格します。ただし、状況によっては試験的機能から非推奨機能に移行する可能性もあります。

試験的機能一覧

以下に、本ドキュメント内に記述している試験的機能の注釈を一覧で表示しています。「記述箇所」のリンクより注釈を記述しているページに移動できます。

Experimental

Asakusa Framework バージョン 0.10.3 では、 TestTookTask は試験的機能として提供しています。

記述箇所

Experimental

Asakusa Framework バージョン 0.10.3 では、 IntelliJ IDEAの利用は試験的機能として提供しています。将来のバージョンで本書の設定手順などが変更になる可能性があります。

本書では、 IntelliJ IDEA バージョン 2017.x を使った利用方法を説明します。バージョンによっては本書とは異なる画面やメニュー体系になっている場合がありますので、詳しくは IntelliJ IDEA のヘルプドキュメントなどを確認してください。

記述箇所

Experimental

Asakusa Framework バージョン 0.10.3 では、Direct I/O CLIは試験的機能として提供しています。

記述箇所

Experimental

Asakusa Framework バージョン 0.10.3 では、 Direct I/O JSON は試験的機能として提供しています。

記述箇所

Experimental

Asakusa Framework バージョン 0.10.3 では、Direct I/O の入力フィルターは試験的機能として提供しています。

記述箇所

Experimental

Asakusa Framework バージョン 0.10.3 では、Direct I/O のHive連携機能は試験的機能として提供しています。

記述箇所

Experimental

Asakusa Framework バージョン 0.10.3 では、 Asakusa on Spark Iterative Extensions は試験的機能として提供しています。

記述箇所

Experimental

Asakusa Framework バージョン 0.10.3 では、入出力データの変換機能は試験的機能として提供しています。

記述箇所

非推奨機能

非推奨機能とは、Asakusa Frameworkのバージョンアップに伴う機能整理などにより利用を推奨しなくなった機能です。

非推奨機能は今後のメンテナンスは基本的に行われず、将来のバージョンで利用出来なくなる可能性があります。非推奨機能の多くは代替となる機能が利用可能であり、各非推奨機能やリリースノートなどのドキュメントに記載の方法で代替機能を利用することを推奨します。

非推奨機能一覧

以下に、本ドキュメント内に記述している非推奨機能の注釈を一覧で表示しています。「記述箇所」のリンクより注釈を記述しているページに移動できます。

Deprecated

本書「Asakusa Gradle Plugin:非推奨機能」では、Asakusa Framework バージョン 0.10.3 で非推奨となっている Asakusa Gradle Plugin の機能をまとめています。本書に記載する機能は、いくつかの制約の元で動作するか、すでに使用できなくなっています。

記述箇所

Deprecated

Asakusa Framework バージョン 0.10.0 以降、 Direct I/O TSV は非推奨機能となりました。 TSV形式のデータフォーマットを扱うには Direct I/O formatted text を利用することを推奨します。

記述箇所

Deprecated

Asakusa Framework 0.10.0 以降、 com.asakusafw.m3bp.buffer.access に unsafe を指定することは非推奨となりました。

記述箇所

Deprecated

Asakusa Framework バージョン 0.10.0 以降、Asakusa on MapReduce、および本書からリンクするAsakusa on MapReduce関連機能は非推奨機能となりました。詳しくは、バージョン 0.10.0 の リリースノート を参照してください。

記述箇所

Deprecated

Asakusa Framework バージョン 0.10.0 以降、 spark.input.direct および spark.output.direct を false に指定した利用は非推奨となりました。

spark.input.direct , spark.output.direct のいずれかの値を false に設定した場合、 YAESSによるバッチアプリケーション実行にはHadoopコマンドを利用できる環境が必要です。利用するHadoopコマンドの設定方法や検索方法については、 YAESSユーザーガイド を参照してください。

記述箇所

Deprecated

Asakusa Framework バージョン 0.10.0 以降、 WindGate TSV は非推奨機能となりました。代わりに WindGate CSV や、 Direct I/O formatted text を利用してください。

記述箇所

Deprecated

本バージョンでは、 YAESS JobQueueの利用は非推奨となっています。

記述箇所

ライセンス

Asakusa Frameworkは Apache License, Version 2.0 [http://www.apache.org/licenses/] の元で公開しています。

                                 Apache License
                           Version 2.0, January 2004
                        http://www.apache.org/licenses/

   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION

   1. Definitions.

      "License" shall mean the terms and conditions for use, reproduction,
      and distribution as defined by Sections 1 through 9 of this document.

      "Licensor" shall mean the copyright owner or entity authorized by
      the copyright owner that is granting the License.

      "Legal Entity" shall mean the union of the acting entity and all
      other entities that control, are controlled by, or are under common
      control with that entity. For the purposes of this definition,
      "control" means (i) the power, direct or indirect, to cause the
      direction or management of such entity, whether by contract or
      otherwise, or (ii) ownership of fifty percent (50%) or more of the
      outstanding shares, or (iii) beneficial ownership of such entity.

      "You" (or "Your") shall mean an individual or Legal Entity
      exercising permissions granted by this License.

      "Source" form shall mean the preferred form for making modifications,
      including but not limited to software source code, documentation
      source, and configuration files.

      "Object" form shall mean any form resulting from mechanical
      transformation or translation of a Source form, including but
      not limited to compiled object code, generated documentation,
      and conversions to other media types.

      "Work" shall mean the work of authorship, whether in Source or
      Object form, made available under the License, as indicated by a
      copyright notice that is included in or attached to the work
      (an example is provided in the Appendix below).

      "Derivative Works" shall mean any work, whether in Source or Object
      form, that is based on (or derived from) the Work and for which the
      editorial revisions, annotations, elaborations, or other modifications
      represent, as a whole, an original work of authorship. For the purposes
      of this License, Derivative Works shall not include works that remain
      separable from, or merely link (or bind by name) to the interfaces of,
      the Work and Derivative Works thereof.

      "Contribution" shall mean any work of authorship, including
      the original version of the Work and any modifications or additions
      to that Work or Derivative Works thereof, that is intentionally
      submitted to Licensor for inclusion in the Work by the copyright owner
      or by an individual or Legal Entity authorized to submit on behalf of
      the copyright owner. For the purposes of this definition, "submitted"
      means any form of electronic, verbal, or written communication sent
      to the Licensor or its representatives, including but not limited to
      communication on electronic mailing lists, source code control systems,
      and issue tracking systems that are managed by, or on behalf of, the
      Licensor for the purpose of discussing and improving the Work, but
      excluding communication that is conspicuously marked or otherwise
      designated in writing by the copyright owner as "Not a Contribution."

      "Contributor" shall mean Licensor and any individual or Legal Entity
      on behalf of whom a Contribution has been received by Licensor and
      subsequently incorporated within the Work.

   2. Grant of Copyright License. Subject to the terms and conditions of
      this License, each Contributor hereby grants to You a perpetual,
      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
      copyright license to reproduce, prepare Derivative Works of,
      publicly display, publicly perform, sublicense, and distribute the
      Work and such Derivative Works in Source or Object form.

   3. Grant of Patent License. Subject to the terms and conditions of
      this License, each Contributor hereby grants to You a perpetual,
      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
      (except as stated in this section) patent license to make, have made,
      use, offer to sell, sell, import, and otherwise transfer the Work,
      where such license applies only to those patent claims licensable
      by such Contributor that are necessarily infringed by their
      Contribution(s) alone or by combination of their Contribution(s)
      with the Work to which such Contribution(s) was submitted. If You
      institute patent litigation against any entity (including a
      cross-claim or counterclaim in a lawsuit) alleging that the Work
      or a Contribution incorporated within the Work constitutes direct
      or contributory patent infringement, then any patent licenses
      granted to You under this License for that Work shall terminate
      as of the date such litigation is filed.

   4. Redistribution. You may reproduce and distribute copies of the
      Work or Derivative Works thereof in any medium, with or without
      modifications, and in Source or Object form, provided that You
      meet the following conditions:

      (a) You must give any other recipients of the Work or
          Derivative Works a copy of this License; and

      (b) You must cause any modified files to carry prominent notices
          stating that You changed the files; and

      (c) You must retain, in the Source form of any Derivative Works
          that You distribute, all copyright, patent, trademark, and
          attribution notices from the Source form of the Work,
          excluding those notices that do not pertain to any part of
          the Derivative Works; and

      (d) If the Work includes a "NOTICE" text file as part of its
          distribution, then any Derivative Works that You distribute must
          include a readable copy of the attribution notices contained
          within such NOTICE file, excluding those notices that do not
          pertain to any part of the Derivative Works, in at least one
          of the following places: within a NOTICE text file distributed
          as part of the Derivative Works; within the Source form or
          documentation, if provided along with the Derivative Works; or,
          within a display generated by the Derivative Works, if and
          wherever such third-party notices normally appear. The contents
          of the NOTICE file are for informational purposes only and
          do not modify the License. You may add Your own attribution
          notices within Derivative Works that You distribute, alongside
          or as an addendum to the NOTICE text from the Work, provided
          that such additional attribution notices cannot be construed
          as modifying the License.

      You may add Your own copyright statement to Your modifications and
      may provide additional or different license terms and conditions
      for use, reproduction, or distribution of Your modifications, or
      for any such Derivative Works as a whole, provided Your use,
      reproduction, and distribution of the Work otherwise complies with
      the conditions stated in this License.

   5. Submission of Contributions. Unless You explicitly state otherwise,
      any Contribution intentionally submitted for inclusion in the Work
      by You to the Licensor shall be under the terms and conditions of
      this License, without any additional terms or conditions.
      Notwithstanding the above, nothing herein shall supersede or modify
      the terms of any separate license agreement you may have executed
      with Licensor regarding such Contributions.

   6. Trademarks. This License does not grant permission to use the trade
      names, trademarks, service marks, or product names of the Licensor,
      except as required for reasonable and customary use in describing the
      origin of the Work and reproducing the content of the NOTICE file.

   7. Disclaimer of Warranty. Unless required by applicable law or
      agreed to in writing, Licensor provides the Work (and each
      Contributor provides its Contributions) on an "AS IS" BASIS,
      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
      implied, including, without limitation, any warranties or conditions
      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
      PARTICULAR PURPOSE. You are solely responsible for determining the
      appropriateness of using or redistributing the Work and assume any
      risks associated with Your exercise of permissions under this License.

   8. Limitation of Liability. In no event and under no legal theory,
      whether in tort (including negligence), contract, or otherwise,
      unless required by applicable law (such as deliberate and grossly
      negligent acts) or agreed to in writing, shall any Contributor be
      liable to You for damages, including any direct, indirect, special,
      incidental, or consequential damages of any character arising as a
      result of this License or out of the use or inability to use the
      Work (including but not limited to damages for loss of goodwill,
      work stoppage, computer failure or malfunction, or any and all
      other commercial damages or losses), even if such Contributor
      has been advised of the possibility of such damages.

   9. Accepting Warranty or Additional Liability. While redistributing
      the Work or Derivative Works thereof, You may choose to offer,
      and charge a fee for, acceptance of support, warranty, indemnity,
      or other liability obligations and/or rights consistent with this
      License. However, in accepting such obligations, You may act only
      on Your own behalf and on Your sole responsibility, not on behalf
      of any other Contributor, and only if You agree to indemnify,
      defend, and hold each Contributor harmless for any liability
      incurred by, or claims asserted against, such Contributor by reason
      of your accepting any such warranty or additional liability.

   END OF TERMS AND CONDITIONS

   APPENDIX: How to apply the Apache License to your work.

      To apply the Apache License to your work, attach the following
      boilerplate notice, with the fields enclosed by brackets "[]"
      replaced with your own identifying information. (Don't include
      the brackets!)  The text should be enclosed in the appropriate
      comment syntax for the file format. We also recommend that a
      file or class name and description of purpose be included on the
      same "printed page" as the copyright notice for easier
      identification within third-party archives.

   Copyright [yyyy] [name of copyright owner]

   Licensed under the Apache License, Version 2.0 (the "License");
   you may not use this file except in compliance with the License.
   You may obtain a copy of the License at

       http://www.apache.org/licenses/LICENSE-2.0

   Unless required by applicable law or agreed to in writing, software
   distributed under the License is distributed on an "AS IS" BASIS,
   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
   See the License for the specific language governing permissions and
   limitations under the License.

ドキュメントの方針

ドキュメントビルド環境の構築

ドキュメンテーションの構成

ToDo

ドキュメントビルド環境の構築

ドキュメントビルド環境

本ドキュメントは、 Sphinx [http://sphinx.pocoo.org/] を利用してビルドします。 Sphinx [http://sphinx.pocoo.org/] のインストール方法は、 sphinx-users.jp [http://sphinx-users.jp/] などを参照して下さい。

ドキュメンテーションの構成

プロジェクトの構成

ドキュメンテーションのプロジェクトを <root>/docs に配置する。

ルートディレクトリの構成

プロジェクトのルートディレクトリは、以下のような構成とする

プロジェクトディレクトリの構成

パス

内容

source/

ドキュメントのソースファイルを格納するディレクトリ

build/

ビルド結果を格納するディレクトリ (自動生成)

README

プロジェクトについての解説

LICENSE

ライセンス情報

make.bat

Windows環境でドキュメントをビルドするバッチ

Makefile

Unix系環境でドキュメントをビルドするmakeファイル

ソースディレクトリの構成

プロジェクトのソースディレクトリは、以下のような構成とする。

ソースディレクトリの構成

パス

内容

_static

静的ファイルを配置するディレクトリ

conf.py

ドキュメントの構成設定情報

index.rst

プロジェクトのマスタードキュメント

<component>/index.rst

コンポーネントごとのマスタードキュメント

コンポーネント

ソースディレクトリ以下にコンポーネントごとにディレクトリを作成し、関連するドキュメントを配置する。

コンポーネントの例

パス

コンポーネント

内容

./

フレームワーク

インデックスやリリースノート、サイトマップ等

intruduction/

フレームワークの紹介

フレームワークの概要説明、入門ドキュメント、開発の流れ

application/

アプリケーション開発環境の整備

開発環境構築手順やバッチアプリケーションのビルド手順等

dmdl/

Asakusa Data Model

DMDLおよびDMDLコンパイラ

dsl/

Asakusa DSL

各種DSLおよびコンパイラ

testing/

TestDriver

テストドライバー

directio/

Direct I/O

Direct I/O

windgate/

WindGate

WindGate

thundergate/

ThunderGate

ThunderGate

yaess/

YAESS

YAESS

administration/

運用環境の整備

運用環境へのデプロイメント手順等

product/

プロダクトについて

ライセンス条項やFAQ、対応プラットフォーム等

documentation/

Documentation

ドキュメントの書き方等 (内部向け)

ドキュメントの形式

ドキュメントは Sphinx [http://sphinx.pocoo.org/] でビルド可能な reStructuredText [http://docutils.sourceforge.net/rst.html] 形式で記述し、拡張子は *.rst とする。

日本語

基本的には「ですます」で記述し、仕様書等は「だである」で記述する。

ドキュメントのターゲット

以下のうち誰を対象とするかを想定すること。

User (U): Asakusa Frameworkを利用してバッチアプリケーションを開発する人

Administrator (A): Asakusa Frameworkを利用して開発されたバッチアプリケーションを運用する人

Manager (M): Asakusa Frameworkを利用してバッチアプリケーションを開発させる人

Developer (D): Asakusa Frameworkそのものを読んだり、拡張ポイントを利用して拡張したりする人

Insider (I): Asakusa Frameworkそのものを開発する人

ドキュメントファイルの命名規則

ファイル名の規則は以下のとおり。

ドキュメント名は小文字アルファベット、数字、ハイフンのみから構成

同じ内容で言語の異なるドキュメント名は一致させる

標準的なドキュメント名

ありえそうなドキュメントの例。下記に該当するドキュメントは、可能な限り名前をそろえる。下記に該当しないドキュメントは、命名規則の範囲で自由に名前をつけてよい。

標準的なドキュメント名

ドキュメント名

想定対象

内容

index

全員

モジュールの概要や他のドキュメントの参照

faq

全員

FAQ的なもの

start-guide

U, M

最も簡素な方法でモジュールを利用する手順

user-guide

U

バッチアプリケーション開発時に必要なモジュールの公開機能を可能な限り網羅したマニュアル

developer-guide

D

Asakusa Frameworkの拡張ポイントを利用した拡張ガイド

administrator-guide

U, A

運用に関するマニュアル

log-table

U, A

ログ一覧 (コンポーネントに関してまとめて出す)

with-X

U, Aなど

他のコンポーネントXとの連携方法

[X-]specification

I

モジュール[のX (language, extensionなど)]に関連する設計書または仕様書

ToDo

Todo

DMDL > Developer Guide

(The original entry is located in /home/centos/jenkins/workspace/release-asakusafw-documentation/docs/ja/source/dmdl/developer-guide.rst, line 7.)

Todo

Asakusa DSL > Developer Guide

(The original entry is located in /home/centos/jenkins/workspace/release-asakusafw-documentation/docs/ja/source/dsl/developer-guide.rst, line 7.)

Todo

Application Testing > Developer Guide

(The original entry is located in /home/centos/jenkins/workspace/release-asakusafw-documentation/docs/ja/source/testing/developer-guide.rst, line 7.)

Todo

WindGate > Developer Guide

(The original entry is located in /home/centos/jenkins/workspace/release-asakusafw-documentation/docs/ja/source/windgate/developer-guide.rst, line 7.)

クリーニングツールのデプロイ

Attention

バージョン 0.9.0 にて、レガシーモジュールの機能は削除されました。

拡張モジュールのデプロイ

Attention

本ドキュメントに記載されていた内容は、以下のページに移動されました。

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

Asakusa Gradle Plugin ユーザーガイド

Hadoop2系の運用環境でAsakusa Frameworkを利用する

Attention

本ドキュメントに記載されていた内容は、以下のページに移動されました。

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

デプロイメントガイド for DirectI/O

Attention

本ドキュメントに記載されていた内容は、以下のページに移動されました。

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

システム構成の検討

デプロイメントガイド for ThunderGate

Attention

本ドキュメントに記載されていた内容は、以下のページに移動されました。

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

システム構成の検討

デプロイメントガイド for WindGate

Attention

本ドキュメントに記載されていた内容は、以下のページに移動されました。

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

システム構成の検討

Maven Framework Organizer利用ガイド

Warning

Asakusa Framework バージョン 0.8.0 以降では、本書で説明するMavenを使ったデプロイメントは非対応となりました。

バージョン 0.8.0 からはGradleを利用してデプロイメントを行います。詳しくは以下のドキュメントを参照してください。

Asakusa Gradle Plugin ユーザーガイド

開発環境マイグレーションガイド

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

レガシーモジュール利用ガイド

Attention

バージョン 0.9.0 にて、 レガシーモジュールの機能は削除されました。

Mavenアーキタイプ利用ガイド

Warning

Asakusa Framework バージョン 0.8.0 以降では、本書で説明するMavenを使ったアプリケーション開発は非対応となりました。

バージョン 0.8.0 からはGradleを利用してアプリケーション開発を行います。詳しくは以下のドキュメントを参照してください。

Asakusa Gradle Plugin ユーザーガイド

開発環境マイグレーションガイド

SDKアーティファクト利用ガイド

Warning

Asakusa Frameworkのバージョン 0.10.0 以降、SDKアーティファクトは利用できません。 SDKアーティファクトの代わりに、 Asakusa Gradle Plugin ユーザーガイド で説明している 依存ライブラリの管理 に従ってアプリケーションプロジェクトを設定してください。

またバージョン0.8系以前のプロジェクトのマイグレーション方法については、 Asakusa Gradle Plugin バージョン 0.9系 の変更点 を参照してください。

この文書では、アプリケーション開発プロジェクト用の依存性定義を行うためのSDKアーティファクトについて説明します。

SDKアーティファクト概要

Asakusa Frameworkではアプリケーションプロジェクトで使用するAsakusa Frameworkのライブラリをグループ化した「SDKアーティファクト」を提供しています。

SDkアーティファクトを利用することで、アプリケーションプロジェクトに対してライブラリの依存性定義をシンプルに過不足なく行うことを支援します。またAsakusa Frameworkのバージョンアップなどに伴うマイグレーション作業を容易にします。

アプリケーションプロジェクトのビルド定義で指定するライブラリにはSDKアーティファクトを使用することを推奨します。

SDKアーティファクト一覧

SDKアーティファクトはAsakusa FrameworkのMavenリポジトリにグループID com.asakusafw.sdk を持つMavenアーティファクトとして登録されています。

Asakusa Frameworkが提供するSDKアーティファクトは以下のものがあります。

Asakusa Framework SDKアーティファクト一覧

アーティファクトID

導入バージョン

説明

asakusa-sdk-core

0.5.0

すべてのアプリケーション開発プロジェクトで共通的に必要となるライブラリをまとめたアーティファクト

asakusa-sdk-windgate

0.5.0

Windgate を使用するアプリケーション開発プロジェクトで必要となるライブラリをまとめたアーティファクト

asakusa-sdk-thundergate

0.5.0

Thundergate を使用するアプリケーション開発プロジェクトで必要となるライブラリをまとめたアーティファクト

asakusa-sdk-directio

0.5.0

Direct I/O を使用するアプリケーション開発プロジェクトで必要となるライブラリをまとめたアーティファクト

asakusa-sdk-hive

0.7.0

Direct I/O Hive を使用するアプリケーション開発プロジェクトで必要となるライブラリをまとめたアーティファクト

asakusa-sdk-test-emulation

0.7.2

エミュレーションモード を使用するアプリケーション開発プロジェクトで必要となるライブラリをまとめたアーティファクト

SDKアーティファクトの利用方法

Asakusa Gradle Plugin ユーザーガイド などの手順で構築したGradleプロジェクトでSDKアーティファクトを使用する場合は、ビルドスクリプトの dependencies ブロック内にSDKアーティファクトの定義を追加します。

以下、SDKアーティファクトを利用したビルドスクリプトの設定例です。

build.gradle

dependencies {
    compile group: 'com.asakusafw.sdk', name: 'asakusa-sdk-core', version: asakusafw.asakusafwVersion
    compile group: 'com.asakusafw.sdk', name: 'asakusa-sdk-directio', version: asakusafw.asakusafwVersion
    compile group: 'com.asakusafw.sdk', name: 'asakusa-sdk-windgate', version: asakusafw.asakusafwVersion
    testRuntime group: 'com.asakusafw.sdk', name: 'asakusa-sdk-test-emulation', version: asakusafw.asakusafwVersion
}

YAESSログの可視化

Attention

バージョン 0.9.0 にて、 YAESSログの可視化の機能は削除されました。

Asakusa DSL Compiler for MapReduce リファレンス

Attention

本ドキュメントに記載されていた内容は、以下のページに移動されました。

Asakusa on MapReduce リファレンス

Asakusa Framework スタートガイド for Windows

Attention

本ドキュメントに記載されていた内容は、以下のページの内容と統合されました。

Asakusa Framework スタートガイド

また、Shafuに関する一部の説明は、以下のShafuのドキュメントに移動しました。

Shafu - Asakusa Gradle Plug-in Helper for Eclipse - [https://docs.asakusafw.com/jinrikisha/ja/html/shafu.html]

ロードマップ

ロードマップについては、ソースリポジトリ上のマイルストーンを参照してください。

https://github.com/asakusafw/asakusafw/milestones

Amazon EMR上でAsakusa Frameworkを利用する

Attention

本ドキュメントに記載されていた内容は、以下のページに移動されました。

Amazon EMR上でAsakusa Frameworkを利用する

Asakusa Vanilla

Attention

本ドキュメントに記載されていた内容は、以下のページに移動されました。

Asakusa Vanilla

Asakusa FrameworkとHiveを連携して利用する

Attention

本ドキュメントに記載されていた内容は、以下のページに移動されました。

Asakusa FrameworkとHiveを連携して利用する

Direct I/O のテキストファイル連携

Attention

本ドキュメントに記載されていた内容は、以下のページに移動されました。

Direct I/O line

Direct I/O TSV

Attention

本ドキュメントに記載されていた内容は、以下のページに移動されました。

Direct I/O TSV

試験的機能

Attention

本ドキュメントに記載されていた内容は、以下のページに移動されました。

試験的機能

IntelliJ IDEAの利用

Attention

本ドキュメントに記載されていた内容は、以下のページに移動されました。

IntelliJ IDEAの利用

WindGate TSV

Attention

本ドキュメントに記載されていた内容は、以下のページに移動されました。

WindGate TSV

Cache for ThunderGate

この文書では、ThunderGateのキャッシュの使い方を概説します。

キャッシュ利用の準備

キャッシュを利用するには、ThunderGateが利用するデータベース上に、次のシステムテーブルが追加で必要になります。

CREATE  TABLE __TG_CACHE_INFO (
    CACHE_ID VARCHAR(128) NOT NULL,
    CACHE_TIMESTAMP DATETIME NOT NULL,
    BUILT_TIMESTAMP DATETIME NOT NULL,
    TABLE_NAME VARCHAR(64) NOT NULL,
    REMOTE_PATH VARCHAR(255) NOT NULL,
    ACTIVE BOOL NOT NULL,
    PRIMARY KEY (CACHE_ID),
    INDEX I_CACHE_INFO_TABLE_NAME (TABLE_NAME)
) ENGINE=InnoDB;

CREATE  TABLE __TG_CACHE_LOCK (
    CACHE_ID VARCHAR(128) NOT NULL,
    EXECUTION_ID VARCHAR(128) NOT NULL,
    ACQUIRED DATETIME NOT NULL,
    PRIMARY KEY (CACHE_ID),
    INDEX I_CACHE_LOCK_EXECUTION_ID (EXECUTION_ID)
) ENGINE=InnoDB;

前者の __TG_CACHE_INFO は作成したキャッシュの情報を管理するテーブルです。また、後者の __TG_CACHE_LOCK はキャッシュに対するロックを管理するテーブルです。いずれも初期データは不要で、何らかの理由でキャッシュが破損した場合には、上記テーブルの内容を全て削除することで初期化できます。

これらのシステムテーブルはThunderGateのシステムテーブル作成用スクリプト 1 を実行することで生成されます。

1

開発環境ではビルド時に自動的に生成されます。運用環境についてはシステムテーブル作成スクリプトを実行します。詳しくは ThunderGateユーザーガイド を参照してください。

Attention

補助インポーター ( Asakusa DSLとThunderGateの連携 を参照) でキャッシュを利用する場合、 そこにも上記のテーブルを用意してください。

キャッシュの仕組み

ThunderGateのキャッシュ機能を有効にした場合、テーブルのインポート処理が行われた後にもそのインポートしたデータをHadoopクラスター上に保存しておきます。

次回に同じテーブルをインポートする際に、ThunderGateは前回インポートしたデータと今回インポートするデータの差分を検出し、変更がない部分については前回保存したデータを最利用します。このため、変更頻度が低い巨大なテーブルでキャッシュを利用すると、ThunderGateのインポート時間を大幅に削減できます。

Attention

現在、ThunderGateのキャッシュが有効なのはインポート時のみです。エクスポートによってデータの大半が書き換えられてしまうようなケースでは、あまり効果がありません。

差分更新

ThunderGateでは、差分データを「最終更新時刻」を元に計算します。これにはThunderGateのシステムカラム UPDT_DATETIME を利用しており、最後にキャッシュを作成した時刻以降に変更のあったデータのみを差分データとして抽出します。

抽出した差分データをHadoopクラスター上に転送したのち、前回インポートしたデータと作成した差分データを MapReduce でマージ処理します。この処理によって、前回のインポートからの変更を反映したデータを高速に作成します。

また、ここで作成したデータは、次回の差分更新時に「前回のインポート結果」として再利用します。つまり、キャッシュを利用すると、最初のインポート時にすべてのデータを転送した後は、毎回のインポートに前回からの差分データのみを転送することになります。

Attention

キャッシュを正しく利用するため、ThunderGateの外部からデータベースの内容を変更する際には、必ず UPDT_DATETIME カラムにデータベース上の現在時刻 ( NOW() ) を指定しなければなりません。

削除フラグ

インポート対象したレコードに「削除フラグ」が設定されている場合、そのレコードはキャッシュ上で自動的に削除されます。現在のキャッシュ機構では、レコードの削除を行う前に必ず削除フラグを設定してキャッシュに反映させる必要があります。

削除フラグの指定方法については、 論理削除をサポートするデータモデル を参照してください。

Warning

削除フラグを設定せずにレコードを削除した場合、そのレコードはキャッシュ上に残り続けてしまいます。その場合、 キャッシュ管理情報の破棄 などの方法で、作成されたキャッシュを一度無効化する必要があります。

キャッシュデータの格納先

キャッシュのデータはファイルシステム上の次の位置に保存されます。

HDFS

/user/<ユーザー名>/thundergate/cache/<ターゲット名>/<テーブル名>/<キャッシュID>

ローカルファイルシステム (スタンドアロンモード時)

~/thundergate/cache/<ターゲット名>/<テーブル名>/<キャッシュID>

キャッシュはさらに、上記ディレクトリの以下に配置されます。

キャッシュディレクトリ内の内容

パス

内容

HEAD/cache.properties

キャッシュの管理情報

HEAD/part-*

キャッシュされたテーブルデータ

キャッシュID

それぞれのキャッシュには「キャッシュID」が与えられていて、その情報を元に利用するキャッシュデータを特定しています。

このIDはコンパイラがインポート対象ごとに自動的に計算します。この計算には、次の設定値を利用します。

ターゲット名 (ThunderGateが利用するデータベースの設定情報)

データモデルクラス名

インポートする対象のテーブル名

インポートする対象のカラム名一覧 (順不同)

上記の項目が変更された場合、キャッシュIDが変わってしまうため、それまで利用していたキャッシュデータは無効化されます。

Note

現在のキャッシュIDの算出方法は、可能な限り同じ意味のデータに対してキャッシュを共有できるようにしています。ただし、２つ以上の処理が同時にひとつのキャッシュを利用できないため、キャッシュIDが衝突してしまう場合には手動で設定してください。手動での設定方法は キャッシュ運用上の注意 を参照してください。

キャッシュの利用

ThunderGateのキャッシュを利用する方法は簡単です。

まず、データベースを解析してデータモデルを作成する際に、 キャッシュをサポートするデータモデル として作成します。つぎに、キャッシュを利用したいインポート処理に対して、 キャッシュ利用の宣言 を行います。

この2つで、ThunderGateは自動的にキャッシュを利用したインポートを行います。

キャッシュをサポートするデータモデル

バージョン0.2.3以降を利用しているプロジェクトの場合、データベースのテーブル情報を元に生成されるデータモデルには自動的にキャッシュをサポートする情報が付加 2 されます。そのようなDMDLをコマンドから生成する場合には、 DMDLとThunderGateの連携 を参照してください。

Attention

古いAsakusa Frameworkのバージョンを利用している場合、生成されるデータモデルはキャッシュをサポートしていません。キャッシュをサポートするように変換する場合、 開発環境マイグレーションガイド を参照してください。

2

implements com.asakusafw.thundergate.runtime.cache.ThunderGateCacheSupport

論理削除をサポートするデータモデル

キャッシュをサポートするデータモデルに、さらに削除フラグを利用した論理削除をサポートさせるには、テーブルからデータモデルを生成する際のオプションを変更します。

Gradleプロジェクトを利用する場合、 build.gradle の asakusafw ブロック内の thundergate プロパティに次の内容を設定します。

論理削除のサポート

項目

内容

deleteColumn

削除フラグのカラム名

deleteValue

削除フラグが成立する値

削除フラグのカラムに利用できる型は以下に限られています。それぞれの値は、整数、ダブルクウォートした文字列、または大文字の論理値で指定します。

利用できる型と値

型

値の例

CHAR, VARCHAR

"1", "T", "D", など

TINYINT

1, 0, など

BOOLEAN

TRUE, FALSE

上記の情報は、データベースに対して1組のみ指定できます。テーブルに削除フラグのカラムが定義されていない場合には、それに対応するデータモデルが削除をサポートしません。

Attention

データベース内で削除フラグの構造が異なる場合については現在サポートしていません。

DMDLを生成するコマンドで上記を指定する場合には、 DMDLとThunderGateの連携 を参照してください。

キャッシュ利用の宣言

インポート時にキャッシュを利用するには、 DbImporterDescription 3 クラスの isCacheEnabled() メソッドをオーバーライドし、 true を返すようにします。

public class SomeImporter extends DbImporterDescription {

    @Override public Class<?> getModelType() {
        return SomeDataModel.class;
    }

    @Override public String getTargetName() {
        return "asakusa";
    }

    @Override public LockType getLockType() {
        return LockType.UNUSED;
    }

    @Override
    public DataSize getDataSize() {
        return DataSize.LARGE;
    }

    @Override public boolean isCacheEnabled() {
        return true;
    }
}

上記の他に、 computeCacheId() をオーバーライドすることで、キャッシュIDに好きな値を利用できます。

なお、キャッシュを利用する際には次の制約があります。

getModelType() に指定できるのは キャッシュをサポートするデータモデル のみ

getWhere() は指定できない ( null を返す必要がある)

getLockType() に指定できるのは UNUSED, TABLE, CHECK のみ

getDataSize() に指定できるのは UNKNOWN, LARGE のみ

Note

この制約は今後緩和される可能性があります。

3

com.asakusafw.vocabulary.bulkloader.DbImporterDescription [https://docs.asakusafw.com/0.10.3/release/api/com/asakusafw/vocabulary/bulkloader/DbImporterDescription.html]

キャッシュ運用上の注意

ThunderGateのキャッシュを運用するにあたって、以下の点に注意する必要があります。

同一のキャッシュIDを利用するジョブは、同時に2つ以上動作させられません

動作させようとした場合、ThunderGateがエラー終了します

DbImporterDescription.computeCacheId() をオーバーライドしてキャッシュIDを書き換えることで対処できます 4

キャッシュを利用するテーブルのレコードを削除する前に、削除フラグをキャッシュに伝搬させる必要があります

詳しくは レコードの物理削除 を参照してください

キャッシュが壊れている場合、差分転送ではなく全データの転送を行います

データベースやHadoopクラスターが障害から復旧した際などに破損している場合があります

正しく動作しない場合には キャッシュのメンテナンス を参照してください

4

ただし、キャッシュデータが2重に作られるようになるため、Hadoopクラスターのディスク容量を余計に必要とします。また、キャッシュIDの算出方法については キャッシュID を参照してください。

キャッシュデータの手動ビルド

テーブルのスキーマを変更したり、テーブルの内容を大幅に変更するなどした場合、次回のキャッシュ生成時に長い時間がかかる場合があります。その場合、あらかじめ手動でキャッシュをビルドしておくことにより、次回のキャッシュ生成時のコストを削減できます。

キャッシュビルドを行うには、 $ASAKUSA_HOME/bulkloader/bin/build-cache.sh コマンドを利用します。このコマンドには次の引数を指定してください。

キャッシュ手動ビルドツールの引数

位置

内容

1

ターゲット名

2

バッチID

3

フローID

4

テーブル名

上記のコマンドを指定すると、対象のバッチの対象のジョブフローに含まれる、対象のテーブルに対するキャッシュをビルドします。この時、次のようなことに注意してください。

テーブルに対するロックの設定は全て無視されます (ただし、キャッシュロックは取得します)

対象のターゲット名に含まれないテーブルは指定できません

対象のジョブフローに含まれないテーブルは指定できません

なお、キャッシュデータの手動ビルドに失敗した場合、安全のためキャッシュロックを取得したままコマンドが終了します。このキャッシュロックを解除するには「 キャッシュロックの解除 」の手順に従ってください。

キャッシュのメンテナンス

キャッシュ機能を利用する場合、ThunderGateは「状態」を持ってしまうことになります。何らかの不整合が発生した場合の対処方法について紹介します。

キャッシュロックの解除

ThunderGateのキャッシュ機構は、ThunderGate本体とは別の方法でロックの処理を行なっています。このロックはインポート処理の手前で取得され、エクスポート処理後に解放されます。

何らかの理由でキャッシュのロックが解放されなかった場合、次のいずれかの方法で開放できます。

$ASAKUSA_HOME/bulkloader/bin/release-cache-lock.sh コマンドを利用する

$ASAKUSA_HOME/bulkloader/bin/dbcleaner.sh コマンドを利用する

前者はターゲット名と実行IDを指定して、そのジョブフローに関する最低限のロックを開放します。また、実行IDを指定しなかった場合には、すべてのキャッシュロックを開放します。

後者はThunderGateのあらゆる管理情報を初期化します。その処理の過程で、キャッシュのロックも全て開放します。

レコードの物理削除

キャッシュの対象となったテーブルのレコードを実際に削除するには、その前に「削除フラグ」を設定してインポートし、キャッシュに削除を反映させておく必要があります。そのため、削除フラグを設定して、すべてのキャッシュにそのフラグを伝搬されるまで、レコードを削除してはいけません。

それぞれのテーブルに対して、キャッシュが反映されている時刻を調べるには、次のような問い合わせを行います。

SELECT TABLE_NAME, MIN(BUILT_TIMESTAMP) FROM __TG_CACHE_INFO GROUP BY TABLE_NAME

キャッシュ管理情報の破棄

キャッシュが何らかの理由で破損してしまった場合や、キャッシュIDの変更により利用されなくなった場合には、キャッシュの管理情報を破棄できます。キャッシュの削除は、 $ASAKUSA_HOME/bulkloader/bin/delete-cache-info.sh コマンドを利用します。

キャッシュ管理情報削除ツールの引数

サブコマンド

残りの引数

内容

cache

target-name cache-id

指定したキャッシュIDのキャッシュのみを破棄します

table

target-name table-name

指定したテーブルに関するキャッシュをすべて破棄します

all

target-name

すべてのキャッシュを破棄します

安全のため、この操作ではキャッシュ管理情報の無効化のみを行います。実際にキャッシュデータを削除する場合には、 キャッシュ領域の開放 を実行してください。

キャッシュ領域の開放

キャッシュ管理情報の破棄 を行った場合、そのキャッシュは「無効なキャッシュ」としてマークされます。この状態で同じキャッシュIDに対してキャッシュが作成された場合、そのキャッシュに使用していた領域が再利用されます。

対象のキャッシュが今後利用されない場合、 $ASAKUSA_HOME/bulkloader/bin/gc-cache-storage.sh コマンドを利用してキャッシュ用の領域を開放します。このコマンドには、引数として対象のターゲット名を指定します。

Note

キャッシュ領域を解放すると、キャッシュ管理情報とキャッシュデータが完全に削除されます。キャッシュ管理情報を先に削除してしまうとキャッシュデータはゴミとして残ってしまうため、その場合には キャッシュデータの手動削除 の方法で削除してください。

Attention

キャッシュ領域の開放を行う際、開放中のキャッシュ領域が再利用されることを防ぐためにキャッシュのロックを取得しようとします。キャッシュのロックが衝突して開放がうまくいかない場合、 キャッシュロックの解除 を実行してください。

キャッシュデータの手動削除

キャッシュデータを手動で削除するには、以下のディレクトリ以下をファイルシステム上から削除します。

HDFS

/user/<ユーザー名>/thundergate/cache/<ターゲット名>/<テーブル名>/<キャッシュID>

ローカルファイルシステム (スタンドアロンモード時)

~/thundergate/cache/<ターゲット名>/<テーブル名>/<キャッシュID>

キャッシュデータが削除されている場合、次回のインポート時に差分転送ではなく全データの転送を行います。

外部システムとの連携 - ThunderGate

ThunderGateは「オンラインシステムのRDBMSとHadoopの連携」を念頭に置いたデータ転送ツールで、主に以下のような特徴があります。

バッチ処理中のデータに対する排他制御をサポート

ジョブフロー内でのロングランニングトランザクションをサポート

変更差分のみをインポートするキャッシュ機能をサポート

MySQL向けに最適化を実施

テーブルメタデータからのデータモデル自動生成

ただし、ThunderGateでサポートしているプラットフォームや構成に制約があります。

現在はMySQLのみ対応

データベースサーバー上での実行が必要

ThunderGate用の管理テーブルや管理カラムが必要

RDBMSと連携する汎用的なツールは、 外部システムとの連携 - WindGate も参照してください。

関連するドキュメント

ThunderGate スタートガイド

ThunderGateユーザーガイド

DMDLとThunderGateの連携

Asakusa DSLとThunderGateの連携

ThunderGateを利用したアプリケーションのテスト

Cache for ThunderGate

ThunderGate スタートガイド

この文書では、ThunderGateの簡単な利用方法について紹介します。なお、 Asakusa Framework スタートガイド の内容を実施し、その内容を理解している前提で説明を進めているため、そちらも参照してください。

ThunderGateの詳しい利用方法については ThunderGateユーザーガイド を参照してください。

ThunderGateを使ったアプリケーションの開発環境構築

ThunderGateを使ったアプリケーションの開発環境を構築する場合、 Asakusa Framework スタートガイド - 開発環境の準備 で構築した開発環境の設定に加えて、以下に示す設定を行う必要があります。

OSのセキュリティ設定

開発環境でThunderGateを実行させる場合、OS毎に以下の設定を行ってください。

CentOS

SELinuxは無効にしてください。

Ubuntu

ThunderGateはMySQLのクエリーを使ってローカルファイルへの入出力を行いますが、Ubuntuなどの一部のディストリビューションではデフォルト設定でMySQLのローカルファイルへの入出力がAppArmorサービスによって制限されています。このため、Ubuntuなどの一部のディストリビューションではAppArmorの設定を変更してMySQLのローカルファイルへの入出力を行えるようにする必要があります。

Ubuntuでは、以下のようにAppArmorの設定を変更します。

sudo mv /etc/apparmor.d/usr.sbin.mysqld /etc/apparmor.d/disable/
sudo /etc/init.d/apparmor restart

sshの設定

開発環境上のOSユーザーに対して、localhostに対するssh接続をパスフレーズ無しで実行出来るよう設定します。以下設定例です。

ssh-keygen -t dsa -P '' -f ~/.ssh/id_dsa
cat ~/.ssh/id_dsa.pub >> ~/.ssh/authorized_keys
chmod 600 ~/.ssh/authorized_keys

MySQLのインストールとユーザー、データベース作成

開発環境にMySQLをインストールします。

MySQLのインストールが完了したら、Asakusa Frameworkのデータモデルクラス生成、およびテストドライバーによるテスト時に使われるMySQLユーザーとデータベースを作成します

後述するAsakusa Frameworkのインストールを行う際に、デフォルトの設定ではThunderGateが使用するデータベース名とユーザー名、パスワードはそれぞれ asakusa に設定されるため、以下ではこのデフォルト値に沿ってデータベースを構築します。

mysql -u root
> GRANT ALL PRIVILEGES ON *.* TO 'asakusa'@'localhost' IDENTIFIED BY 'asakusa' WITH GRANT OPTION;
> GRANT ALL PRIVILEGES ON *.* TO 'asakusa'@'%'IDENTIFIED BY 'asakusa' WITH GRANT OPTION;
> CREATE DATABASE asakusa DEFAULT CHARACTER SET utf8;
exit

Warning

このデータベースはアプリケーションのビルド実行毎に再作成(DROP DATABASE/CREATE DATABASE）が行われるので、開発以外の目的では使用しないでください。

アプリケーションの開発準備

ThunderGateを利用したバッチアプリケーションを新しく作成する場合、 Asakusa Gradle Plugin ユーザーガイド で説明するGradleプロジェクトのテンプレートを利用すると簡単です。

以降、このドキュメントではこのテンプレートから作成したプロジェクトを利用して説明を進めます。

Gradleプロジェクトの設定

GradleプロジェクトでThunderGateを使用する場合は build.gradle に対して以下の定義を追加します。

開発環境用の JDBC接続設定 ファイルを配置する

asakusafw ブロックに thundergate.jdbcFile <JDBC接続設定ファイルのパス> を追加

Framework Organizerに対してThunderGateの構成を有効化する

asakusafwOrganizer ブロックに thundergate.enabled true を追加

ThunderGate用SDKを依存関係に追加する

dependencies ブロックの compile に対して asakusa-sdk-thundergate を 追加

dependencies ブロックの compile に対して mysql-connector-java を 追加

以下、 build.gradle の設定例です。

asakusafw {
    ...

    thundergate.jdbcFile 'src/dist/common/bulkloader/conf/asakusa-jdbc.properties'
}

asakusafwOrganizer {
    thundergate.enabled true
    ...
}

dependencies {
    compile group: 'com.asakusafw.sdk', name: 'asakusa-sdk-core', version: asakusafw.asakusafwVersion
    compile group: 'com.asakusafw.sdk', name: 'asakusa-sdk-thundergate', version: asakusafw.asakusafwVersion
    compile group: 'mysql', name: 'mysql-connector-java', version: '5.1.25'
    ...

上記の設定後、 installAsakusafw タスクを実行して開発環境のAsakusa Frameworkを再インストールします。

Eclipseを利用している場合は、 eclipse タスクを実行してEclipseのプロジェクト情報を再構成します。

JDBC接続設定

ThunderGateはRDBMSに対してJDBC接続を経由してデータの入出力を行います。ThunderGateはジョブフローの入出力データをRDBMSから読み書きする対象を「ターゲット」として抽象化しています。DSLではJDBCの接続情報そのものは指定せずに、入出力を行うターゲット名のみを指定します。

ターゲットに対するJDBC接続設定を定義したプロパティファイルは、 $ASAKUSA_HOME/bulkloader/conf 配下に <ターゲット名>-jdbc.properties という名前で配置します。標準ではターゲット名 asakusa 用のJDBC接続定義ファイルとして asakusa-jdbc.properties が配置されています。

また、開発環境では DMDLとThunderGateの連携 で説明する、DDLからDMDLスクリプトを生成する機能が利用できます。このときDDLの登録先であるMySQLのデータベース接続設定情報をもつJDBC接続設定ファイルを build.gradle の thundergate.jdbcFile に設定します。

Hint

このファイルは $ASAKUSA_HOME/bulkloader/conf/asakusa-jdbc.properties をコピーして作成することもできます。

JDBC接続設定について詳しくは、 ThunderGateユーザーガイド - JDBC接続設定ファイル を参照してください。

データベースノード用設定

ThunderGateはRDBMSがインストールされているサーバー（データベースノード）とHadoopクラスター上のある特定のサーバー（Hadoopクライアントマシン）間でデータを転送します。ThunderGateはデータベースノード、HadoopクライアントマシンそれぞれにThunderGateのモジュールをデプロイし、設定を行う必要があります。

データベースノードに対する設定を定義したプロパティファイルは、 $ASAKUSA_HOME/bulkloader/conf 配下に bulkloader-conf-db.properties という名前で配置します。開発環境については通常はデフォルトのままで動作するよう設定されていますが、必要に応じて設定を変更してください。

データベースノード用設定について詳しくは、 ThunderGateユーザーガイド - データベースノード用ThunderGate設定ファイル を参照してください。

Hadoopクライアントマシン用設定

このガイドでは、開発環境はデータベースノードとHadoopクライアントマシンは同一のマシンであることを前提とします。このため、開発環境でデータベースノード用の設定に加えてHadoopクライアントマシン用の設定を行います。

Hadoopクライアントマシンに対する設定を定義したプロパティファイルは、 $ASAKUSA_HOME/bulkloader/conf 配下に bulkloader-conf-hc.properties という名前で配置します。データベースノード用の設定と同様、この設定ファイルも開発環境については通常はデフォルトのままで動作するよう設定されていますが、必要に応じて設定を変更してください。

Hadoopクライアント用設定について詳しくは、 ThunderGateユーザーガイド - Hadoopクライアントマシン用ThunderGate設定ファイル を参照してください。

サンプルプログラムの実行

アプリケーションの開発準備 で作成したプロジェクトには、サンプルのアプリケーションが用意されています。このサンプルは Asakusa Framework スタートガイド のサンプルアプリケーション（カテゴリー別売上金額集計バッチ）の内容をThunderGate向けに書きなおしたもので、以下のデータベーステーブルに対してデータの入出力を行います。

サンプルアプリケーションが利用するテーブル

テーブル名

入力/出力

概要

SALES_DETAIL

入力

売上トランザクション

STORE_INFO

入力

店舗マスタ

ITEM_INFO

入力

商品マスタ

CATEGORY_SUMMARY

出力

カテゴリ別売上集計

ERROR_RECORD

出力

エラー情報

サンプルアプリケーションのビルド

サンプルアプリケーションのビルドを行います。処理内容や手順は Asakusa Framework スタートガイド と同様です。ここではビルドコマンドのみを示します。

Warning

ビルド時に実行されるモデル生成処理(Gradleの compileDMDL タスクにて実行)時に、 MySQLのインストールとユーザー、データベース作成 で作成したデータベースが再作成(DROP/CREATE)されます。このデータベースには重要なデータを配置しないでください。

コマンドラインコンソールでアプリケーションプロジェクトのディレクトリに移動し、以下のコマンドを実行してください。

./gradlew build

サンプルデータの配置

サンプルアプリケーションプロジェクトには、 Asakusa Framework スタートガイド で説明したWindGateのサンプルアプリケーションと同様に src/test/example-dataset 以下にサンプルの入力ファイルが配置されています。ThunderGateではデータの入出力はMySQLのテーブルとなるため、このCSVをMySQLの各テーブルにインポートします。

サンプルアプリケーションプロジェクトには、このCSVファイルのデータをMySQLの各テーブルにインポートするためのSQLファイルのサンプルが src/test/sql/import-example-dataset.sql に置かれています。このファイルを使ってサンプルデータをセットする例を以下に示します。

コマンドラインコンソールでアプリケーションプロジェクトのディレクトリに移動し、以下のコマンドを実行してください。

cp -r src/test/example-dataset /tmp
mysql -u asakusa -pasakusa -D asakusa < src/test/sql/import-example-dataset.sql

アプリケーションの実行

アプリケーション実行の手順は Asakusa Framework スタートガイド と同様です。

ここではコマンド例のみを示します。詳しくは同文書の サンプルアプリケーションのデプロイ と サンプルアプリケーションの実行 を参考にしてください。

cd <サンプルアプリケーションプロジェクトのパス>
cp target/*batchapps*.jar $ASAKUSA_HOME/batchapps
cd $ASAKUSA_HOME/batchapps
jar xf *batchapps*.jar

$ASAKUSA_HOME/yaess/bin/yaess-batch.sh example.summarizeSales -A date=2011-04-01

サンプルアプリケーションの実行 との相違点として、結果の出力はローカルファイルシステムではなく、MySQLのテーブルに出力されます。

アプリケーション実行結果の確認

サンプルアプリケーションが出力するテーブルを参照します。以下例です。

mysql -u asakusa -pasakusa -D asakusa -e "SELECT * FROM CATEGORY_SUMMARY"
+-----+------------+---------------------+---------------------+---------------+--------------+---------------------+
| SID | VERSION_NO | RGST_DATETIME       | UPDT_DATETIME       | CATEGORY_CODE | AMOUNT_TOTAL | SELLING_PRICE_TOTAL |
+-----+------------+---------------------+---------------------+---------------+--------------+---------------------+
|   1 |       NULL | 2012-07-30 13:15:52 | 2012-07-30 13:15:52 | 1300          |           12 |                1596 |
|   2 |       NULL | 2012-07-30 13:15:52 | 2012-07-30 13:15:52 | 1401          |           15 |                1470 |
|   3 |       NULL | 2012-07-30 13:15:52 | 2012-07-30 13:15:52 | 1600          |           28 |                5400 |
+-----+------------+---------------------+---------------------+---------------+--------------+---------------------+

mysql -u asakusa -pasakusa -D asakusa -e "SELECT * FROM ERROR_RECORD"
+-----+------------+---------------------+---------------------+---------------------+------------+---------------+---------+
| SID | VERSION_NO | RGST_DATETIME       | UPDT_DATETIME       | SALES_DATE_TIME     | STORE_CODE | ITEM_CODE     | MESSAGE |
+-----+------------+---------------------+---------------------+---------------------+------------+---------------+---------+
|   1 |       NULL | 2012-07-30 13:15:52 | 2012-07-30 13:15:52 | 1990-01-01 10:40:00 | 0001       | 4922010001000 | ????    |
|   2 |       NULL | 2012-07-30 13:15:52 | 2012-07-30 13:15:52 | 2011-04-01 19:00:00 | 9999       | 4922010001000 | ????    |
|   3 |       NULL | 2012-07-30 13:15:52 | 2012-07-30 13:15:52 | 2011-04-01 10:00:00 | 0001       | 9999999999999 | ????    |
+-----+------------+---------------------+---------------------+---------------------+------------+---------------+---------+

アプリケーションの開発

以降ではアプリケーションの開発における、ThunderGate特有の部分について紹介します。

データモデルクラスの生成

データモデルクラスを作成するには、データモデルの定義情報を記述後にGradleの compileDMDL タスクを実行します。

ThunderGateではモデルをDMDLで記述するほかにThunderGate特有の機能として、ThunderGateが入出力に利用するデータベースのテーブル定義情報を記述したDDLスクリプトや、結合や集計を定義した専用のビュー定義情報を記述したDDLスクリプトから対応するDMDLスクリプトを生成出来るようになっています。

DMDLスクリプトはプロジェクトの src/main/dmdl ディレクトリ 1 以下に配置し、スクリプトのファイル名には .dmdl の拡張子を付けて保存します。 DMDLの記述方法については DMDLスタートガイド などを参考にしてください。

またテーブルやビューのDDLスクリプトからDMDLスクリプトを生成する機能を使う場合、DDLスクリプトはプロジェクトの src/main/sql/modelgen ディレクトリ以下に配置し、DDLスクリプトのファイル名には .sql の拡張子を付けて保存します。

DDLスクリプトは compileDMDL タスク実行時に一時的にDMDLスクリプトに変換され 2 、続けて src/main/dmdl 配下のDMDLと合わせてデータモデルクラスを生成します。 DDLスクリプトの記述方法については DMDLとThunderGateの連携 を参照してください。

1

ディレクトリはプロジェクトの設定ファイル build.properties で変更可能です。

2

一時的に出力されるDMDLスクリプトは、 target/dmdl ディレクトリ以下に出力されます。このディレクトリはプロジェクトの設定ファイル build.properties で変更可能です。

Asakusa DSLの記述

ThunderGateを利用する場合でも、Asakusa DSLの基本的な記述方法は同様です。

ThunderGate特有の部分は、ThunderGateとの連携を定義するジョブフロー記述の部分になります。ここではMySQLのテーブルに対する入出力の抽出条件や使用するロックの種類などを定義します。詳しくは Asakusa DSLとThunderGateの連携 を参照してください。

それ以外の部分については、 Asakusa DSLスタートガイド などを参照してください。

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

Asakusa DSLの記述と同様、アプリケーションのテストについても基本的な方法は同じで、テストドライバーを利用することが出来ます。

ThunderGateはMySQLに対してデータの入出力を行うため、ジョブフローのテストについてはテストドライバー側でテストデータ定義に基づいてMySQLに対する初期データの投入や結果の取得が行われます。ThunderGateを利用したアプリケーションのテストについて詳しくは ThunderGateを利用したアプリケーションのテスト を参照してください。

それ以外の部分については、 アプリケーションテストスタートガイド などを参照してください。

ThunderGateユーザーガイド

この文書では、ThunderGateの利用方法について紹介します。

機能と構成の概要

ThunderGateは、バッチアプリケーションが処理するデータを管理するRDBMSとHadoopクラスター間でデータを転送するツールです。 RDBMSがインストールされているサーバー（データベースノード）とHadoopクラスター上のある特定のサーバー（Hadoopクライアントマシン）間の二点間でデータを転送します。

ThunderGateと連携したバッチアプリケーションを作成する場合、通常はそれぞれのジョブフローの入力と出力時にそれぞれThunderGateの処理が実行されます。たとえば、ジョブフローの処理の開始時にThunderGateを利用して、データベースの内容をHadoopクラスター上に展開し（インポート）、処理の終了時に計算結果をデータベースに書き戻します（エクスポート）。

対応RDBMS

ThunderGateが対応するRDBMSは MySQL 1 2 のみとなっています。ThunderGateはインポートとエクスポートに MySQL に依存した処理を実行することでMySQL向けに最適化されています。

1

http://www.mysql.com/

2

対応しているバージョンの詳細については、 対応プラットフォーム を参照してください。

プロセスの概要

ThunderGateはデータベースノードとHadoopクライアントマシンにそれぞれ配置したモジュールが連携して動作します。ThunderGateの各プロセスは YAESS などの外部のワークフローエンジンから起動され、処理の完了とともにプロセスが終了します。 また、ThunderGateは運用時に手動で環境をメンテナンスするためのコマンドラインツールを提供しています。

ThunderGateが提供するプロセスの一覧とその概要を以下に示します。

ThunderGateのプロセス概要

プロセス

実行ノード

概要

インポータ

データベースノード

RDBMSからデータを取得し、Hadoopクライアントマシン上のエクストラクタの実行を介してHadoopクライアントマシンにデータを送信する

エクストラクタ

Hadoopクライアントマシン

インポータから転送されたデータをHadoopファイルシステムに配置する。

エクスポータ

データベースノード

Hadoopクライアントマシン上のコレクタの実行を介してHadoopクライアントマシンからデータを受信し、RDBMSへ登録/更新する

コレクタ

Hadoopクライアントマシン

Hadoopファイルシステムのデータを取得し、エクスポータに送信する。

リカバラ

データベースノード

ジョブフローの実行状態に基づいて、必要に応じて処理のロールバックまたはロールフォワードを処理を行う。

運用ツール群

データベースノード

ThunderGateの管理情報やキャッシュデータのメンテナンスを実行する。

Note

システム構成の検討 の説明では便宜的に、データベースノードに配置するモジュールを「ThunderGate」または「ThunderGate本体」, Hadoopクライアントマシンに配置するモジュールを「ThunderGate Hadoopブリッジ」 という呼称を使って説明を行っています。

データソースとターゲット

ThunderGateが処理の対象とするデータベース群を「データソース」と呼びます。データソースはシステム全体で複数存在することがあります。Asakusa DSLからあるデータソースを特定するための識別子を「ターゲット」と呼びます。

ThunderGateはRDBMSに対してJDBC接続を行うことでデータの転送を行いますが、DSLではRDBMSに対する接続設定を直接指定せずに、入出力を行うターゲットのみを指定します。ジョブフローの実行時にはターゲットからRDBMSの接続設定を引き当て、その接続情報を利用してデータの入出力を行います。

入力のアーキテクチャ

ThunderGateの入力（インポート）には次のような特徴があります。

処理対象データに対する排他制御

複数データソースに対するデータ入力

差分インポート用に入力データをHadoopクラスターにキャッシュ

処理対象データに対する排他制御

ThunderGateを利用したバッチアプリケーションは、ジョブフローを実行する際に処理対象とするデータ（データベースのテーブル、及びレコード）に対してロックをかけることが出来ます。このロックは以下のような用途を想定しています。

同じテーブル、もしくはレコードを参照/更新する複数のバッチアプリケーションが同時に実行される可能性があり、バッチ間の排他制御を行う必要がある場合。

Webアプリケーションなどのオンラインシステムとデータベースを共有する場合で、バッチアプリケーションとオンラインアプリケーション間の排他制御を行う必要がある場合。

ThunderGateのロックは、対象となるアプリケーションがThunderGate用の 管理テーブル や 管理カラム 3 の値を判断して実現する論理的なロック 4 です。このため、バッチアプリケーションと連携するオンラインアプリケーションは、ThunderGateが提供するロック機構に従ってアプリケーションのロック戦略を決定し、アプリケーションを実装する必要があるかもしれません。オンラインアプリケーションとの連携については、 オンラインアプリケーションとの連携 にて後述します。

バッチアプリケーションでは、DSLを介してアプリケーションが取得するロック対象のテーブルやその ロックの種類 を指定します。

3

ThunderGateを利用する上で必要となる、バッチアプリケーションの処理対象となるテーブルに付随して定義するテーブルやカラムです。詳しくは後述の テーブル定義 にて解説します。

4

RDBMS自体が持つロック機構を使用したロックではありません。

ロックの種類

ThunderGateを利用したアプリケーションが指定できるロックの種類を示します。

ロックの種類

ロック種別

概要

TABLE

インポート対象のテーブル全体をロックする。ロックの取得に失敗したらエラーとする。

ROW

インポート対象のレコードのみをロックする。ロックの取得に失敗したらエラーとする。

ROW_OR_SKIP

インポート対象のレコードのみをロックする。ロックの取得に失敗したらそのレコードをインポート対象から除外する。

CHECK

ロックの有無を確認するがロックは取得しない。ロックが行われていたらエラーとする。

UNUSED

あらゆるロック操作を行わない。

ThunderGateを利用したアプリケーションは、ジョブフロー記述のDSLを介して使用するロックの種類を指定します。詳しくは Asakusa DSLとThunderGateの連携 を参照してください。

複数データソースに対するデータ入力

ThunderGateは原則として、1つのジョブフローで扱うデータソースは1つとしていますが、以下の制約を前提として例外的に1つのジョブフローで複数のデータソースを扱うことが出来ます。

エクスポート及びロックを行うことが出来るデータソースは1つのみ。

これは、参照と更新を行うトランザクションデータと参照のみを行うマスタデータを異なるデータソースで管理している場合に、この制約の元でデータをインポートすることを想定しています。複数データソースに対するデータ入力はAsakusa DSLが提供する「補助インポータ」と呼ばれるDSLを利用して実現します。

差分インポート用に入力データをHadoopクラスターにキャッシュ

ThunderGateは差分インポートを実現するためのキャッシュ機構を提供しています。

ジョブフローのDSLの指定によりキャッシュ機能を有効にすることで、ThunderGateはテーブルのインポートが行われた後にもそのインポートしたデータをHadoopクラスター上に保存（キャッシュ）するようになります。次回に同じテーブルをインポートする際に、ThunderGateは前回インポートしたデータと今回インポートするデータの差分を検出し、変更がない部分については前回保存したデータを最利用します。

このため、変更頻度が低い巨大なテーブルでキャッシュを利用すると、ThunderGateのインポート時間を大幅に削減できます。

キャッシュ機能の使用方法について詳しくは、 Cache for ThunderGate を参照してください。

出力のアーキテクチャ

ThunderGateの出力（エクスポート）には次のような特徴があります。

出力データのマージ更新

出力のアトミック処理

重複チェック

出力データのマージ更新

ThunderGateは出力データをRDBMSに書き戻す際に、アプリケーション内で新規作成されたデータか、入力データに対する更新データであるかをテーブルのキー 5 に基づいて判断し、データの挿入、もしくは更新を自動的に選択するマージ更新を行います。

5

テーブルのキーには後述する 管理カラム のシステムIDを使用します。

Note

WindGateではデータの書き戻し時には対象となるテーブルをTRUNCATEした後にINSERTを行い、マージ処理が必要な場合はWindGateの外側で出力データのマージ処理を行うことを想定していますが、ThunderGateでは先述のロック機構と合わせて、連携するオンラインアプリケーションが直接利用するテーブルに対して出力することを想定しています。

出力のアトミック処理

出力のアトミック処理とは、ジョブフローの実行がなにかしらの理由により正常に終了しなかった場合に、データソースの内容をロールバック、もしくはロールフォワードして、データソースが持つデータの不整合を解消する機構です。

ThunderGateはジョブフローの処理途中でエラーが発生した場合、データベースに保持するThunderGate用のシステム情報からジョブフローの進捗状況を判断し、データソースをジョブフロー実行前の状態に戻す（ロールバック）か、データソースをジョブフローが正常に終了する場合と同じ状態になるように処理を進める（ロールフォワード）ことを試みます。

ThunderGateは出力のアトミック処理を実現するために、エクスポート処理の課程でエクスポート対象データを作成し、これを「ステージング領域」 6 に展開し、このステージング領域からエクスポート対象のテーブルに展開します。

リカバリ時にロールバックを行うか、ロールフォワードを行うかは、以下の基準に従って判断されます。

エクスポート処理において、ステージング領域からエクスポート対象のテーブルに対して一部のデータの更新/挿入が始まっている場合は、ロールフォワードが試みられる。

上記1以外の場合は、ロールバックが試みられる。

ThunderGateはジョブフローの異常終了時にワークフロー定義に従ってリカバリ処理を自動で実行します。また手動でリカバリを実行するためのコマンドラインインターフェースを提供しています。手動でのリカバリはアプリケーション実行環境の障害などで異常終了も行なわれなかったような状況において利用することを想定しています。

6

ステージング領域はエクスポート処理時に一時的に作成される、エクスポート対象のテーブル構造と同じ構造をもつ「エクスポートテンポラリテーブル」と、エクスポートテンポラリテーブルを管理するシステムテーブルなどから構成されます。

重複チェック

重複チェックとはエクスポート時に特定のカラムの値が同じである「重複データ」が既にデータベース上にあるかどうかをチェックを行い、そのようなデータを通常のエクスポート対象テーブルに書き戻すかわりにエラー情報用のテーブルに書き戻すという機能です。

この機能は、データベースのキーとは別に業務的に意味のある項目に対してチェックを行う 7 もので、これは通常業務ロジックとして扱うような処理になりますが、エクスポートのタイミングで行うことで業務ロジックを効率的に実装することを意図しています。

重複チェックを利用するには、重複チェック用のテーブルを用意し、重複チェック用のロジックをDSLの定義に記述します 8 。

7

例えば、「受注伝票から出荷伝票を新規に作成するバッチアプリケーションで、作成した出荷伝票データをエクスポートする際に、伝票番号と伝票区分をキー項目として重複チェックを行う」といったように利用することを想定しています。

8

重複チェックのDSL定義については、 Asakusa DSLとThunderGateの連携 を参照してください。

ThunderGateの設定

ThunderGateの各設定ファイルは、 $ASAKUSA_HOME/bulkloader/conf ディレクトリ配下に配置します。ThunderGateの設定ファイルの一覧を下表に示します。

ThunderGateの設定ファイル一覧

種類

ノード

設定ファイル名

JDBC接続設定ファイル

データベースノード

<ターゲット名>-jdbc.properties

データベースノード用ThunderGate設定ファイル

データベースノード

bulkloader-conf-db.properties

Hadoopクライアントマシン用ThunderGate設定ファイル

Hadoopクライアントマシン

bulkloader-conf-hc.properties

環境変数設定スクリプト

データベースノード/Hadoopクライアントマシン

env.sh

ログ設定ファイル

データベースノード/Hadoopクライアントマシン

log4j.xml

拡張子が .properties の設定ファイルは、Javaの一般的なプロパティファイルの文法で設定項目を定義しますが、プロパティファイルのすべての項目の値には ${環境変数名} という形式で環境変数を含めることができます。

JDBC接続設定ファイル

JDBC接続設定ファイルは、ターゲットに対するJDBC接続設定を定義します。このプロパティファイルは $ASAKUSA_HOME/bulkloader/conf 配下にターゲット毎に <ターゲット名>-jdbc.properties という名前で配置します。

JDBC接続設定ファイル

名前

既定値

値

jdbc.driver

JDBCドライバー名

jdbc.url

JDBCドライバーURL

jdbc.user

JDBC接続ユーザー名

jdbc.password

JDBC接続パスワード

database.name 9

RDBMSのデータベース名

db.parameter 10

JDBC接続プロパティファイルパス

9

通常は設定する必要はありません。レガシーモジュールのテストドライバーが使用する設定ファイルとフォーマットを統一するために設定ファイルのテンプレートに項目が含まれています。レガシーモジュールについては、 レガシーモジュール利用ガイド を参照してください。

10

JDBC接続時に渡すプロパティを記述したプロパティファイルのパスを絶対パスで指定します。チューニングパラメータなどを渡す必要がある場合に使用することを想定しています。

データベースノード用ThunderGate設定ファイル

データベースノード用ThunderGate設定ファイル ($ASAKUSA_HOME/bulkloader/conf/bulkloader-conf-db.properties) は、データベースノードで動作するThunderGateのプロセスの動作を設定します。

データベースノード用ThunderGate設定ファイルは、設定の対象によって以下のセクションに分類されます。

データベースノード用ThunderGate設定ファイルの項目

セクション名

内容

データベースノード共通設定

データベースノードで動作する各プロセス共通の設定

インポート設定 (データベースノード)

データベースノードで実行されるインポートの動作に関する設定

エクスポート設定 (データベースノード)

データベースノードで実行されるエクスポートの動作に関する設定

管理カラム設定

業務テーブルに必要な管理カラムの設定 11

重複チェック機能設定

重複機能に関する設定

以降では、それぞれのセクションに対する設定項目について説明します。

11

業務テーブルや管理カラムについては、後述の テーブル定義 を参照してください。

データベースノード共通設定

データベースノードで動作する各プロセス共通の設定を記述します。

データベースノード共通設定

名前

既定値

値

log.conf-path

bulkloader/conf/log4j.xml

各プロセスが使用する Log4J の設定ファイルパス (絶対パス)

ssh.path

各プロセスがHadoopクライアントマシンの接続時に使用する ssh コマンドのパス

hadoop-cluster.host

Hadoopクライアントマシンのホスト名

hadoop-cluster.user

Hadoopクライアントマシンのログインユーザー名

hadoop-cluster.env.ASAKUSA_HOME

HadoopクライアントマシンのAsakusa Frameworkのインストールパス

hadoop-cluster.env.HADOOP_CMD

Hadoopクライアントマシンが利用する hadoop コマンドのパス。 12

12

オプション項目です。HADOOP_CMDが不要なHadoopディストリビューションを使用している場合は設定しないでください。

インポート設定 (データベースノード)

データベースノードで行われるインポートに関する設定を記述します。

インポート設定 (データベースノード)

名前

既定値

値

import.tsv-create-dir

インポートデータの中間ファイルを出力するディレクトリ (絶対パス) 。このディレクトリはRDBMSの実行ユーザー,及びThunderGateの実行するユーザーの両ユーザーに対して READ と WRITE の権限が必要。

import.zip-comp-type

NONE

Hadoopクライアントマシンにデータを転送する際に、転送データの圧縮を行うか。 NONE: 圧縮しない, COMPRESS: 圧縮する

import.zip-comp-buf-size

32768

転送データの圧縮時に使用するバッファサイズ(byte)

import.retry-count

3

リトライ可能エラーが発生した場合のリトライ試行回数

import.retry-interval

10

リトライ可能エラーが発生した場合のリトライインターバル(秒数)

import.delete-tsv

DELETE

処理が正常終了した場合、 import.tsv-create-dir に生成された中間ファイルを削除するか。 DELETE: 削除する, KEEP: 削除しない

エクスポート設定 (データベースノード)

データベースノードで行われるエクスポート処理に関する設定を記述します。

エクスポート設定 (データベースノード)

名前

既定値

値

export.tsv-create-dir

エクスポートデータの中間ファイルを出力するディレクトリ (絶対パス) 。このディレクトリはRDBMSの実行ユーザー,及びThunderGateの実行するユーザーの両ユーザーに対して READ と WRITE の権限が必要。

export.zip-comp-buf-size

32768

転送データの受信時に使用するバッファサイズ(byte)

export.retry-count

3

リトライ可能エラーが発生した場合のリトライ試行回数

export.retry-interval

10

リトライ可能エラーが発生した場合のリトライインターバル(秒数)

export.data-copy-max-count

100000

エクスポートデータを業務テーブルにコピーする際の、1トランザクションで処理する最大レコード数

export.delete-tsv

DELETE

処理が正常終了した場合、 export.tsv-create-dir に生成された中間ファイルを削除するか。 DELETE: 削除する, KEEP: 削除しない

管理カラム設定

管理カラムの設定を記述します。管理カラムについて詳しくは後述の 管理カラム を参照してください。

管理カラム設定

名前

既定値

値

table.sys-column-sid

SID

業務テーブルのシステムIDのカラム名

table.sys-column-version-no

VERSION_NO

業務テーブルのバージョン番号のカラム名

table.sys-column-rgst-date

RGST_DATETIME

業務テーブルの登録日時のカラム名

table.sys-column-updt-date

UPDT_DATETIME

業務テーブルの更新日時のカラム名

table.sys-column-temp-sid

__TEMP_SID

エクスポート処理で作成するテンポラリテーブルのシステムSIDのカラム名

重複チェック機能設定

重複チェック機能の設定を記述します。

重複チェック機能設定

名前

既定値

値

dupcheck.index.<バッチID>|<フローID>|<テーブル名>

重複チェック機能で発行されるSQLに対して、 force index 句を追加し、ここで使用するインデックス名を指定。プロパティキーの <バッチID>, <フローID>, <テーブル名> にそれぞれ対象となるバッチID、フローID、テーブル名の値に置き換えて設定する。

Hadoopクライアントマシン用ThunderGate設定ファイル

Hadoopクライアントマシン用ThunderGate設定ファイル ($ASAKUSA_HOME/bulkloader/conf/bulkloader-conf-hc.properties) は、Hadoopクライアントマシンで動作するThunderGateのプロセスの動作を設定します。

Hadoopクライアントマシン用ThunderGate設定ファイルは、設定の対象によって以下のセクションに分類されます。

Hadoopクライアントマシン用ThunderGate設定ファイルの項目

セクション名

内容

Hadoopクライアントマシン共通設定

Hadoopクライアントマシンで動作する各プロセス共通の設定

インポート設定 (Hadoopクライアントマシン)

Hadoopクライアントマシンで行われるインポートの動作に関する設定

エクスポート設定 (Hadoopクライアントマシン)

Hadoopクライアントマシンで行われるエクスポートの動作に関する設定

Hadoopクライアントマシン共通設定

Hadoopクライアントマシンで動作する各プロセス共通の設定を記述します。

Hadoopクライアントマシン共通設定

名前

既定値

値

log.conf-path

bulkloader/conf/log4j.xml

各プロセスが使用する Log4J の設定ファイルパス (絶対パス)

base-path

Hadoopのワーキングディレクトリパスを完全URI 13 で指定。このプロパティを設定しない場合、Hadoopの設定に従ったワーキングディレクトリが使用される。

13

完全URIとはファイルシステム、ホスト、パスを指定した形式です。例えば hdfs://localhost/tmp/asakusa などです。

インポート設定 (Hadoopクライアントマシン)

Hadoopクライアントマシンで行われるインポートに関する設定を記述します。

インポート設定 (Hadoopクライアントマシン)

名前

既定値

値

import.cache-build-max-parallel

キャッシュ機能のキャッシュ構築処理時に関する最大並列処理数 14

Attention

Asakusa Framework 0.7.0 より、設定 import.seq-comp-type は利用できなくなりました。転送時の圧縮はフレームワークが規定する内部の形式を利用するようになります。

14

キャッシュ処理については、 Cache for ThunderGate を参照してください。

エクスポート設定 (Hadoopクライアントマシン)

Hadoopクライアントマシンで行われるエクスポート処理に関する設定を記述します。

エクスポート設定 (Hadoopクライアントマシン)

名前

既定値

値

export.zip-comp-type

NONE

データベースノードにデータを転送する際に、転送データの圧縮を行うか。 NONE: 圧縮しない, COMPRESS: 圧縮する

export.tsv-max-size

16777216

データベースノードにデータを転送する際の1ファイルの最大サイズ (byte) 。この値より大きなファイルをデータベースノードに転送する場合、ファイルが分割されて転送される。

環境変数設定スクリプト

ThunderGateの実行に特別な環境変数を利用する場合、 $ASAKUSA_HOME/bulkloader/conf/env.sh 内でエクスポートして定義できます。

ThunderGateをAsakusa Frameworkのバッチから利用する場合、以下の環境変数が必要です。

ThunderGateの実行に必要な環境変数

名前

備考

JAVA_HOME

JAVAのインストール先パス

ASAKUSA_HOME

Asakusa Frameworkのインストール先パス

特別な理由がない限り、 ASAKUSA_HOME はThunderGateを実行する前 15 にあらかじめ定義しておいてください。 $ASAKUSA_HOME/bulkloader/conf/env.sh では、その他必要な環境変数を定義するようにしてください。

その他、以下の環境変数を利用可能です。

ThunderGateで利用可能な環境変数

名前

備考

HADOOP_CMD

利用する hadoop コマンドのパス。

HADOOP_HOME

Hadoopのインストール先パス。

IMPORTER_JAVA_OPTS

インポータを実行するJava VMの追加オプション

EXPORTER_JAVA_OPTS

エクスポータを実行するJava VMの追加オプション

RECOVERER_JAVA_OPTS

リカバラを実行するJava VMの追加オプション

EXTRACTOR_JAVA_OPTS

エクストラクタを実行するJava VMの追加オプション

COLLECTOR_JAVA_OPTS

コレクタを実行するJava VMの追加オプション

なお、ThunderGateの本体は、以下の規約に従って起動します (上にあるものほど優先度が高いです)。

環境変数に HADOOP_CMD が設定されている場合、 $HADOOP_CMD コマンドを経由して起動します。

環境変数に HADOOP_HOME が設定されている場合、 $HADOOP_HOME/bin/hadoop コマンドを経由して起動します。

hadoop コマンドのパスが通っている場合、 hadoop コマンドを経由して起動します。

このため、 HADOOP_CMD と HADOOP_HOME の両方を指定した場合、 HADOOP_CMD の設定を優先します。

特別な理由がない限り、 $ASAKUSA_HOME/bulkloader/conf/env.sh 内で HADOOP_CMD や HADOOP_HOME を設定しておくのがよいでしょう。または、 YAESS を利用して外部から環境変数を設定することも可能です。

15

YAESS を経由してThunderGateを実行する場合、ThunderGateがデータベース上で利用する環境変数 ASAKUSA_HOME はYAESS側の設定で行えます。また、Hadoopクライアントマシン上で利用する環境変数は データベースノード用ThunderGate設定ファイル で設定することができます。 YAESSについて詳しくは YAESSユーザーガイド を参照してください。

ログ設定ファイル

ThunderGateは内部のログ表示に Log4J 16 を利用しています。ログの設定を変更するには、 $ASAKUSA_HOME/bulkloader/conf/log4j.xml を編集してください。

また、ThunderGateの実行時には以下の値がシステムプロパティとして設定されます。

ThunderGate実行時のシステムプロパティ

名前

値

logfile.basename

プロセス名

16

http://logging.apache.org/log4j/1.2/

Warning

ThunderGateのHadoopクライアントマシンの設定では、ログを標準出力に出力しないようにしてください。データベースノードとHadoopクライアントマシンで標準出力を介したデータ転送を行っているため、標準出力に対するログ出力を行うとデータが正しく転送することが出来ません。なお、標準エラー出力を利用することは問題ありません。

テーブル定義

ThunderGateはデータベースのテーブルに対してデータの入出力を行いますが、ThunderGateを利用する場合、ThunderGate特有のテーブル構造を有する必要があります。

まず、ThunderGateのテーブル定義を説明するにあたって必要となる用語を定義します。

業務テーブル

ThunderGateと連携したバッチアプリケーションがデータの入出力を行う対象となる、業務データを保持するテーブルです。 ThunderGate スタートガイド で説明したサンプルアプリケーションの例では、 売上トランザクション (SALES_DEATAIL) や店舗マスタ (STORE_INFO) といったようなテーブルが該当します。

管理カラム

ThunderGateが業務テーブルに対する処理を制御するための管理情報を保持するカラムです。ThunderGateがデータ入出力を行う業務テーブルは、一部の例外を除きThunderGateが定める管理カラムを持つ必要があります。

管理テーブル

ThunderGateが業務テーブルに対する処理を制御するための管理情報を保持するテーブルです。ThunderGateがデータ入出力を行う業務テーブルは、一部の例外を除きThunderGateが定める管理テーブルを持つ必要があります。

重複エラーテーブル ThunderGateの重複チェック機能を利用する場合に利用するテーブルです。重複チェックを実行結果として重複したレコードが登録されます。バッチアプリケーションが重複チェック機能を利用する場合は、DSLの記述に対応した重複エラーテーブルを用意する必要があります。

システムテーブル

ThunderGateが利用する、ThunderGateの動作を制御するテーブルです。バッチアプリケーションからはこのテーブルを利用しませんが、ThunderGateを利用する環境を構築する際に、一部のシステムテーブルに対して業務テーブルの内容に応じたレコードをセットする必要があります。

以下、それぞれのテーブルについて説明します。

業務テーブル

ThunderGateと連携したバッチアプリケーションがデータの入出力を行う対象となる、業務データを保持するテーブルです。ThunderGateを利用する上で、業務テーブルは以下の制約があります。

各業務テーブルは 管理カラム を持ち、主キー制約を 管理カラム 上のシステムIDに対して定義する。

各業務テーブルは対応する 管理テーブル を持つ。

各業務テーブルのストレージエンジンは INNODB を使用する 17 。

業務テーブルは基本的に上述した 管理カラム と 管理テーブル を定義する必要がありますが、以下の場合については、 管理カラム と 管理テーブル の定義は不要です。

補助インポート機能でのみデータの入力を行う業務テーブル

17

INNODB 以外のストレージエンジンでは動作検証が行われていません。

業務テーブルに対応するデータモデルクラスの作成

ThunderGateはテーブルの定義情報からDMDLを生成する「DMDLジェネレータ」を提供しており、これを利用して業務テーブルのDDLスクリプトからAsakusa DSLで利用するデータモデルクラスを生成することが出来ます 18 。

業務テーブルからデータモデルクラスを生成する場合、業務テーブルのDDLスクリプトをプロジェクトの src/main/sql/modelgen ディレクトリ以下に配置してください。また、スクリプトのファイル名には .sql の拡張子を付けて保存してください 19 。

プロジェクトに対して Gradleの compileDMDL タスクを実行すると、業務テーブルに対応するDMDLスクリプト、及びデータモデルクラスが生成されます 20 。

18

DMDLとの連携について詳しくは DMDLとThunderGateの連携 を参照してください。

19

SQLファイルは複数配置することが出来ます。上記ディレクトリ配下にサブディレクトリを作成し、そこにSQLファイルを配置することも可能です。SQLファイルを複数配置した場合、ディレクトリ名, ファイル名の昇順にSQLが実行されます。

20

データモデルクラスを作成については Mavenアーキタイプ利用ガイド も参照してください。

管理カラム

管理カラムはThunderGateが業務テーブルに対する処理を制御するための管理情報を保持するカラムです。ThunderGateがデータ入出力を行う業務テーブルは、一部の例外を除きThunderGateが定める以下の管理カラムを持つ必要があります。

管理カラム

名前

カラム名 21

必要な制約等

データ型

説明

システムID

SID

主キー制約, DBによる自動採番

BIGINT

レコードを一意に識別するための値

バージョン番号

VERSION_NO

デフォルト値に 1 を設定

BIGINT

レコードのバージョン

登録日時

RGST_DATETIME

DATETIME

レコードの登録日時

更新日時

UPDT_DATETIME

DATETIME

レコードの更新日時

以下に管理カラムを持つ業務テーブルのDDLスクリプト例を示します。

CREATE TABLE SALES_DETAIL(
    -- 管理カラム
    SID                 BIGINT     PRIMARY KEY AUTO_INCREMENT,
    VERSION_NO          BIGINT     NULL,
    RGST_DATETIME       DATETIME   NULL,
    UPDT_DATETIME       DATETIME   NULL,

    -- 業務テーブルのカラム
    SALES_DATE_TIME     DATETIME    NOT NULL,
    STORE_CODE          VARCHAR(50) NOT NULL,
    ...

21

管理カラムのカラム名は データベースノード用ThunderGate設定ファイル の 管理カラム設定 により変更することができます。ここでは標準のカラム名を記載しています。

管理カラムの更新

管理カラムの値は、ThunderGateと連携するバッチアプリケーションとオンラインアプリケーションの排他制御に利用することを想定しています 22 。 ThunderGateはジョブフローの実行時に、エクスポート対象となる業務テーブルの管理カラムに対して以下の通りに更新を行います。

管理カラムの更新

名前

登録時

更新時

バージョン番号

規定のデフォルト値 1 を設定

インポート時の値をインクリメント

登録日時

データベースノードのシステム日付を設定

更新しない

更新日時

データベースノードのシステム日付を設定

データベースノードのシステム日付を設定

管理カラムの値はThunderGateによって更新されるため、バッチアプリケーションの演算子によってデータモデル上の管理カラムの値を編集しないようにしてください。

Warning

特にシステムSIDを演算子の中で更新すると、エクスポート処理が意図しない結果になる可能性があるので注意してください。

22

詳しくは オンラインアプリケーションとの連携 を参照してください。

管理テーブル

管理テーブルはThunderGateが業務テーブルに対する処理を制御するための管理情報を保持するテーブルです。ThunderGateがデータ入出力を行う業務テーブルは、一部の例外を除きThunderGateが定める以下の管理テーブルを持つ必要があります。

管理テーブル

名前

テーブル名

説明

ロック済みレコードテーブル

<業務テーブル名>_RL 23

レコードロックの情報を保持する

23

例えば、業務テーブル SALES_DETAIL に対しては、管理テーブル SALES_DETAIL_RL というテーブルを作成します。

ロック済みレコードテーブル

ロック済みレコードテーブルは、レコードロックの情報を保持する管理テーブルです。ロック済みレコードテーブルのテーブル定義を以下に示します。

ロック済みレコードテーブル

名前

カラム名

必要な制約等

データ型

説明

システムID

SID

ユニークインデックス

BIGINT

業務テーブルの管理カラムのSIDを保持する

ジョブフローSID

JOBFLOW_SID

BIGINT

SID に対応する、レコードをロックしている実行ID(ジョブフロー実行ID) 24 を特定するためのID 25 。

以下に業務テーブルに対応するロック済みレコードテーブルのDDLスクリプト例を示します。

CREATE TABLE SALES_DETAIL_RL (
  SID BIGINT PRIMARY KEY ,
  JOBFLOW_SID BIGINT NULL
) ENGINE=InnoDB;

24

実行IDはジョブフローの実行ごとのIDです。詳しくは YAESSユーザーガイド の実行IDの説明を参照してください。ThunderGateでは実行IDを「ジョブフロー実行ID」という名前で使用しており、ログメッセージなどにはジョブフロー実行IDというメッセージが出力されます。 YAESSを使用している場合は実行IDの値がジョブフロー実行IDと同一になります。

25

ジョブフローSIDから実行ID（ジョブフロー実行ID）を特定するには、後述する システムテーブル の1つであるジョブフロー実行テーブル (RUNNING_JOBFLOWS) テーブルを参照します。ジョブフロー実行テーブルに対してジョブフローSIDを条件として検索を行うことでこのテーブルのレコードを一意に特定出来ます。詳しくは後述の ジョブフロー実行テーブル を参照してください。

管理テーブル用DDLスクリプトの生成

Gradleプロジェクトテンプレートから作成したプロジェクトでは、先述の 業務テーブルに対応するデータモデルクラスの作成 に従って Gradleの compileDMDL タスクを実行すると、業務テーブルに対応する管理テーブル用DDLスクリプトが target/sql 配下に生成され 26 、開発環境用のデータベースに対してこのSQLが実行されます。

ThunderGateが要求するテーブルが自動的に作成されるため、テストドライバーを使ったテストがすぐに行える状態になります。また、このDDLスクリプトを利用して運用環境の構築を行うことができます。

26

生成の対象とする管理テーブルのフィルタリングやDDLスクリプトの出力ディレクトリパス build.properties によって設定可能です。詳しくは Mavenアーキタイプ利用ガイド の ビルド定義ファイルの項を参照してください。

重複エラーテーブル

ThunderGateの重複チェック機能 27 を利用する場合に利用するテーブルです。重複チェックを実行結果として重複したレコードが登録されます。バッチアプリケーションが重複チェック機能を利用する場合は、DSLの記述に対応した重複エラーテーブルを用意する必要があります。

重複エラーテーブルは以下のカラムを持つ必要があります。

重複エラーテーブルに必要なカラム

名前

カラム名

データ型

説明

登録日時

RGST_DATETIME 28

DATETIME

レコードの登録日時

更新日時

UPDT_DATETIME 29

DATETIME

レコードの更新日時

エラーコード

任意のカラム名 30

CHAR または VARCHAR

エラーコード

27

重複チェック機能について、詳しくは Asakusa DSLとThunderGateの連携 の 重複チェック機能 を参照してください。

28

業務テーブルと同じ管理カラム名。設定でカラム名を変更している場合は、それに合わせたカラム名を定義してください。

29

業務テーブルと同じ管理カラム名。設定でカラム名を変更している場合は、それに合わせたカラム名を定義してください。

30

エラーコードのカラム名はAsakusa DSLのジョブフロー記述に設定したエラーコードのカラム名に合わせて定義してください。

システムテーブル

ThunderGateが利用する、ThunderGateの動作を制御するテーブルです。バッチアプリケーションからはこのテーブルを利用しませんが、システムThunderGateを利用した環境を構築する際に、一部のシステムテーブルに対して業務テーブルの内容に応じたレコードをセットする必要があります。

また、運用時に実行中のジョブフローのロック状態を確認する際にシステムテーブルを参照することができます。

ロック管理テーブルのメンテナンス

システムテーブルのうち、テーブルロック管理テーブル (IMPORT_TABLE_LOCK) はThunderGateの処理対象となる業務テーブルのテーブル名をレコードとして保持する必要があります。

このテーブルをメンテナンスするためのSQLスクリプトがAsakusa Frameworkインストールディレクトリ配下の $ASAKUSA_HOME/bulkloader/sql/insert_import_table_lock.sql に配置されています。このスクリプトを実行することで、テーブルロック管理テーブルに必要なレコードが登録されるようになっています。

開発環境については、Gradleプロジェクトテンプレートから作成したプロジェクトでは、先述の 業務テーブルに対応するデータモデルクラスの作成 に従って Gradleの compileDMDL フェーズを実行すると、このSQLスクリプトが合わせて実行されるため、プロジェクト管理下の業務テーブルの情報については自動的にテーブルロック管理テーブルに反映されるようになっています。

運用環境については、テーブルロック管理テーブルを手動でメンテナンスする必要があります。ThunderGateが処理対象となる業務テーブルが追加になり、運用環境のデータベースに業務テーブルが追加されたタイミングで、合わせてこのSQLスクリプトを実行するようにしてください。

ジョブフロー実行テーブル

ジョブフロー実行テーブルはThunderGateと連携したバッチアプリケーションのジョブフローの実行状態を管理するテーブルです。後述する オンラインアプリケーションとの連携 で説明する各システムテーブルの情報と合わせてジョブフローの実行状態を確認するために使用します。

ジョブフロー実行テーブルのテーブル定義を以下に示します。

ジョブフロー実行テーブル

名前

カラム名

データ型

説明

ジョブフローSID

JOBFLOW_SID

BIGINT

実行中のジョブフローのジョブフローSID

バッチID

BATCH_ID

VARCHAR

実行中のジョブフローのバッチID

フローID

JOBFLOW_ID

VARCHAR

実行中のジョブフローのフローID

ターゲット名

TARGET_NAME

VARCHAR

実行中のジョブフローのターゲット名

ジョブフロー実行ID

EXECUTION_ID

VARCHAR

実行中のジョブフローのジョブフロー実行ID

終了予定日時

EXPECTED_COMPLETION_DATETIME

DATETIME

実行中のジョブフローの終了予定時刻 31

31

バージョン 0.10.3 では未使用のため、ダミーの値を固定で挿入しています。

アプリケーションの開発

以降ではアプリケーションの開発における、ThunderGate特有の部分について紹介します。

なお、以降の機能を利用するには次のライブラリやプラグインが必要です 32 。

ThunderGateで利用するライブラリ等

ライブラリ

概要

asakusa-thundergate-vocabulary

DSL用のクラス群

asakusa-thundergate-plugin

DSLコンパイラプラグイン

asakusa-thundergate-test-moderator

テストドライバープラグイン

asakusa-thundergate-dmdl

DMDLコンパイラプラグイン

32

アーキタイプ asakusa-archetype-thundergate から作成したプロジェクトは、これらのライブラリやプラグインがSDKアーティファクトという依存性定義によってデフォルトで利用可能になっています。詳しくは Mavenアーキタイプ利用ガイド や SDKアーティファクト利用ガイド を参照してください。

また、またテーブルやビューのDDLスクリプトからDMDLスクリプトを生成する機能を使う場合は、以下のライブラリも必要です。

ThunderGateのDDL-DMDL連携機能で利用するライブラリ等

ライブラリ

概要

asakusa-regacy-test-driver

レガシーテストドライバープラグイン

データモデルクラスの生成

データモデルクラスを作成するには、データモデルの定義情報を記述後にGradleの compileDMDL タスクを実行します。

ThunderGateではモデルをDMDLで記述するほかにThunderGate特有の機能として、ThunderGateが入出力に利用するデータベースのテーブル定義情報を記述したDDLスクリプトや、結合や集計を定義した専用のビュー定義情報を記述したDDLスクリプトから対応するDMDLスクリプトを生成出来るようになっています。

DMDLスクリプト 33 はプロジェクトの src/main/dmdl ディレクトリ 34 以下に配置し、スクリプトのファイル名には .dmdl の拡張子を付けて保存します。 DMDLの記述方法については DMDLスタートガイド などを参考にしてください。

またテーブルやビューのDDLスクリプトからDMDLスクリプトを生成する機能を使う場合、DDLスクリプトはプロジェクトの src/main/sql/modelgen ディレクトリ以下に配置し、DDLスクリプトのファイル名には .sql の拡張子を付けて保存します。

DDLスクリプトは Gradleの compileDMDL タスク実行時に一時的にDMDLスクリプトに変換され 35 、続けて src/main/dmdl 配下のDMDLと合わせてデータモデルクラスを生成します。 DDLスクリプトの記述方法については DMDLとThunderGateの連携 を参照してください。

33

ここで説明しているDMDLスクリプトはDDLスクリプトから生成するDMDLスクリプトではなく、DMDLスクリプトを一から記述する場合です。

34

ディレクトリはプロジェクトの設定ファイル build.properties で変更可能です。

35

一時的に出力されるDMDLスクリプトは、 target/dmdl ディレクトリ以下に出力されます。このディレクトリはプロジェクトの設定ファイル build.properties で変更可能です。

Asakusa DSLの記述

ThunderGateを利用する場合でも、Asakusa DSLの基本的な記述方法は同様です。

ThunderGate特有の部分は、ThunderGateとの連携を定義するジョブフロー記述の部分になります。ここではRDBMSのテーブルに対する入出力の抽出条件や使用するロックの種類などを定義します。詳しくは Asakusa DSLとThunderGateの連携 を参照してください。

それ以外の部分については、 Asakusa DSLスタートガイド などを参照してください。

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

Asakusa DSLの記述と同様、アプリケーションのテストについても基本的な方法は同じで、テストドライバーを利用することが出来ます。

ThunderGateはRDBMSに対してデータの入出力を行うため、ジョブフローのテストについてはテストドライバー側でテストデータ定義に基づいてRDBMSに対する初期データの投入や結果の取得が行われます。ThunderGateと連携したアプリケーションのテストについて詳しくは ThunderGateを利用したアプリケーションのテスト を参照してください。

それ以外の部分については、 アプリケーションテストスタートガイド などを参照してください。

アプリケーションの運用

以降ではアプリケーションの運用における、ThunderGate特有の部分について紹介します。

運用環境の構築

運用環境の構築についての基本的な内容は、 Asakusa Framework デプロイメントガイド 及び システム構成の検討 を参照してください。

ここでは、ThunderGateのデプロイに特有の部分について説明します。

ThunderGate用テンポラリディレクトリの作成

データベースノードのマシン上では、ThunderGate用の設定に従ってインポータ、エクスポータ処理用のテンポラリテーブルを作成する必要があります。

上述の データベースノード用ThunderGate設定ファイル に設定した以下のプロパティの値を確認します。

import.tsv-create-dir

export.tsv-create-dir

上記の2プロパティに指定したテンポラリ用ディレクトリを作成します。これらのディレクトリのパーミッションはバッチアプリケーションの実行ユーザーとMySQL実行ユーザーの両ユーザーが読み込み、書き込み可能な権限を設定します。

以下設定例です。

mkdir -p -m 777 /var/tmp/asakusa/importer
mkdir -p -m 777 /var/tmp/asakusa/exporter
chown -R mysql:mysql /var/tmp/asakusa

Attention

import.tsv-create-dir, export.tsv-create-dir のデフォルトの設定は /tmp 配下に設定されていますが、一部のOSでは /tmp 配下は再起動時にクリアされるため、必要に応じて設定を変更してください。

バッチアプリケーション用テーブルの作成

バッチアプリケーションが使用する業務テーブルと管理テーブルをMySQLに登録します。

業務テーブルや管理テーブルについては先述の テーブル定義 を参照してください。

ロック管理テーブルのレコード登録

バッチアプリケーション用のテーブルをMySQLに登録後、ロック管理テーブルに対して業務テーブルのテーブル名を登録します。

ロック管理テーブルとそのメンテナンスについて詳しくは後述の ロック管理テーブルのメンテナンス を参照してください。

以下手順例です。

cd $ASAKUSA_HOME/bulkloader/sql
mysql -u appuser -pappuser -D appdb < insert_import_table_lock.sql

なお、アプリケーションの変更に伴い業務テーブルに追加になった場合には、先述の バッチアプリケーション用テーブルの作成 を再度実行するとともに、ロック管理テーブルのレコード登録も再度実行する必要があります。この場合、ロック管理テーブルの古いレコード情報を削除してから、ロック管理テーブルのレコードを再登録してください。以下手順例です。

cd $ASAKUSA_HOME/bulkloader/sql
mysql -u appuser -pappuser -D appdb < delete_import_table_lock.sql
mysql -u appuser -pappuser -D appdb < insert_import_table_lock.sql

トランザクションのメンテナンス

ジョブフローの実行が異常終了した場合などの場合、実行したジョブフローに対してロールバック、もしくはロールフォワードを実行してトランザクションの整合性を保つ必要があります。

リカバラによるトランザクションの整合性維持

ThunderGateではトランザクションの整合性維持のためにリカバラというツールを提供しています。

リカバラはThunderGateの実行状況をThunderGateのシステムテーブルや管理テーブルから判断し、必要に応じてロールバック、またはロールフォワードを実行します。

ThunderGateと連携したバッチアプリケーションを YAESS 経由で実行した場合、リカバラはYAESSの finalize フェーズで実行されるようになっています。この動作によりジョブフローが異常終了した場合、バッチアプリケーションは自動的にトランザクションの整合性を回復するよう試みます 36 。

ただし、YAESS自体が正常に動作せず上記の異常終了シーケンスが実行されなかった場合など、なにかしらの原因によりリカバラが正常に実行されなかった場合についてはトランザクションが中断された状態になります。このような状態になった場合、手動でトランザクションを修復する必要があります。

36

YAESSのフェーズなどについて詳しくは YAESSユーザーガイド を参照してください。

手動によるでトランザクション修復

ThunderGateでは、ジョブフローが異常終了した場合に手動でトランザクションを修復する方法として、以下の2つの方法を提供しています。

リカバラを単体のコマンドとして実行する

DBクリーナーコマンドを実行する

リカバラを単体のコマンドとして実行する

リカバラはYAESSなどのワークフローエンジンと連携して自動で実行するほか、手動で実行することも可能にになっています。リカバラを手動で実行するには $ASAKUSA_HOME/bulkloader/bin/recoverer.sh コマンドを実行します。

以下の形式で指定します。

$ASAKUSA_HOME/bulkloader/bin/recoverer.sh <ターゲット名> <ジョブフロー実行ID>

コマンドに指定可能な引数は以下のとおりです。

<ターゲット名>

対象のデータソースのターゲット

<ジョブフロー実行ID>

対象となるジョブフローのジョブフロー実行ID。この引数を省略した場合、異常終了または中断したと判断されたすべてのジョブフローインスタンスに対してロールバック、またはロールフォワードが試行される。

実行結果はThunderGateのログに出力されるので、内容を確認してください。

DBクリーナーコマンドを実行する

なにかしらの原因でThunderGateの管理情報に不整合が発生し、リカバラを実行しても環境が回復しない場合は、ThunderGateのシステムテーブルや管理テーブルを初期化するためのDBクリーナーコマンドを利用することが出来ます。このコマンドを実行すると、以下の処理が行われます。

ThunderGateのシステムテーブルを初期化

業務テーブルに関連する管理カラム、管理テーブルの内容を初期化

ThunderGateが処理中のテンポラリテーブルが残っていた場合はこれらを全て削除

Warning

DBクリーナーはコマンド実行時に中断しているトランザクションが存在した場合でも、その修復を試みないで環境の初期化が行うため、データの一貫性が損なわれる可能性があります。

またコマンド実行時に正常に処理が進行しているジョブフローが存在した場合、DBクリーナーの実行が原因で処理が中断してしまうため、DBクリーナーの利用は注意が必要です。

DBクリーナーは $ASAKUSA_HOME/bulkloader/bin/dbcleaner.sh コマンドを実行します。

以下の形式で指定します。

$ASAKUSA_HOME/bulkloader/bin/dbcleaner.sh <ターゲット名>

コマンドに指定可能な引数は以下のとおりです。

<ターゲット名>

対象のデータソースのターゲット

オンラインアプリケーションとの連携

ここでは、ThunderGateと連携したバッチアプリケーション (以下「バッチアプリケーション」) とオンラインアプリケーションが同じ業務テーブルに対して処理を行う場合に考慮すべき点を説明します。

ある業務テーブルに対してオンラインアプリケーションが参照または更新を行う際に、データの整合性を確保するためにバッチアプリケーションがその業務テーブル、または業務テーブル中のレコードに対して処理中であるか、または更新済みであるかを確認する必要があるかもしれません。

ThunderGateはオンラインアプリケーションとの連携を行うにあたって、以下の情報を提供します。

業務テーブルに対するテーブルロック

業務テーブルのレコードに対するレコードロック

業務テーブルのレコードに対するバージョン情報

業務テーブルのレコードに対する登録日時と更新日時

以下、それぞれについて説明します。

Attention

ThunderGateと連携したバッチアプリケーションが取得できるロックの種類とロック取得方法については、 Asakusa DSLとThunderGateの連携 のインポート記述の説明を参照してください。

業務テーブルに対するテーブルロック

バッチアプリケーションが業務テーブルに対してテーブルロックを取得しているかどうかは、テーブルロックの情報の保持するシステムテーブル「テーブルロック管理テーブル」( IMPORT_TABLE_LOCK ) を確認します。

テーブルロック管理テーブル IMPORT_TABLE_LOCK のテーブル定義を以下に示します。

テーブルロック管理テーブル: IMPORT_TABLE_LOCK

名前

カラム名

制約

データ型

説明

テーブル名

TABLE_NAME

主キー

VARCHAR

ロック対象のテーブル名

ジョブフローSID

JOBFLOW_SID

BIGINT

ロック対象のジョブフローSID。 NULL はロックが取得されていないことを表す。

このテーブルにはあらかじめThunderGateが扱う業務テーブル毎にレコードが登録されています 37 。ジョブフローSIDカラムの初期値は NULL です。バッチアプリケーションがテーブルロックを取得した場合、該当テーブル名のレコードに対してジョブフローSIDカラムを実行中のジョブフローのジョブフローSIDで更新し、処理が完了したら NULL で更新してロックを解除します。

オンラインアプリケーションは、テーブル名を条件としてレコードを検索し、取得されたレコードのジョブフローSIDカラムの値を確認することでテーブルロックが行われているかを確認することができます。

37

このため、バッチアプリケーションのアップデートなどにより扱う業務テーブルが増えた場合は、テーブルロック管理テーブルにも合わせてレコードを追加する必要があります。詳しくは先述の ロック管理テーブルのメンテナンス を参照してください。

業務テーブルに対するレコードロック

バッチアプリケーションが業務テーブルに対してレコードロックを取得しているかどうかは、以下の2つの方法で確認できます。

レコードロックが行われているテーブルの情報を保持するシステムテーブル「レコードロック管理テーブル」( IMPORT_RECORD_LOCK ) を確認する。

レコードロックが行われているレコードの情報を保持する管理テーブル「ロック済みレコードテーブル」( <業務テーブル>_RL ) を確認する。

テーブル単位でレコードロックを確認したい場合は 1. のレコードロック管理テーブルを、レコード単位でレコードロックを確認したい場合は 2. のロック済みレコードテーブルを確認します。

レコードロック管理テーブル

レコードロック管理テーブル IMPORT_RECORD_LOCK はレコードロックが行われているテーブルの情報を保持します。レコードロック管理テーブル IMPORT_RECORD_LOCK のテーブル定義を以下に示します。

レコードロック管理テーブル: IMPORT_RECORD_LOCK

名前

カラム名

制約

データ型

説明

ジョブフローSID

JOBFLOW_SID

主キー

BIGINT

ロック対象のジョブフローSID。

テーブル名

TABLE_NAME

VARCHAR

ロック対象のテーブル名

このテーブルには初期時にはレコードが登録されていません。バッチアプリケーションがテーブルロックを取得した場合、該当テーブル名のテーブルと実行中のジョブフローSIDを持つレコードを登録し、処理が完了したら該当レコードを削除してロックを解除します。

オンラインアプリケーションは、テーブル名を条件としてレコードを検索し、該当のレコードが存在するかを確認することでレコードロックが行われているかを確認することができます。

ロック済みレコードテーブルによるレコードロックの確認

ロック済みレコードテーブルの定義については、先述の ロック済みレコードテーブル を確認してください。

このテーブルには初期時にはレコードが登録されていません。バッチアプリケーションがレコードロックを取得した場合、該当レコードのシステムSIDと実行中のジョブフローSIDを持つレコードを登録し、処理が完了したら該当レコードを削除してロックを解除します。

オンラインアプリケーションは、業務テーブルに対応するロック済みレコードからシステムSIDを条件としてレコードを検索し、該当のレコードが存在するかを確認することでレコードロックが行われているかを確認することができます。

バージョン情報によるレコード更新の確認

業務テーブルの 管理カラム に含まれるバージョン番号は、バッチアプリケーションが該当レコードをエクスポートする際に、エクスポート対象の業務テーブルが持つ値に対してインクリメント (値を1加算） 38 して更新します。

オンラインアプリケーションはバージョン番号を参照して、オンラインアプリケーションがある時点で参照したデータが更新時にバッチアプリケーションで更新されていないかを確認することができます。

Attention

バージョン番号はエクスポート時に業務テーブルのレコードの値が実際に更新されているかいないかに関わらず値がインクリメントされます。

38

インポート時の値ではなく、エクスポート時のレコードの値に対してインクリメントされます。

登録日時と更新日時によるレコード更新の確認

業務テーブルの 管理カラム に含まれる登録日時と更新日時は、バッチアプリケーションが該当レコードをエクスポートする際に、それぞれの値が更新されます。詳しくは、 管理カラムの更新 を参照してください。

バージョン情報によるレコード更新の確認 と同様に、オンラインアプリケーションはこれらの値を参照して、オンラインアプリケーションがある時点で参照したデータが更新時にバッチアプリケーションで更新されていないかを確認することができます。

DMDLとThunderGateの連携

Asakusa Framework 0.2では、ThunderGateが利用しているデータベースのテーブル定義情報や、ビューの定義情報などから対応するDMDLスクリプトを生成できるようになっています。このため、0.1で提供していたモデルジェネレータは非推奨となりました。

0.2以降では、ThunderGateが利用しているMySQLのメタデータを分析し、対応するデータモデルをDMDLの形式で生成する「DMDLジェネレータ」を提供しています。

MySQLのメタデータからDMDLを生成する

DMDLジェネレータはMySQLに登録されたテーブル定義やビュー定義から、 DMDLのレコードモデル、結合モデル、集計モデルをそれぞれ生成します。

テーブル定義 (レコードモデル)

ビュー定義 (結合モデル)

ビュー定義 (集計モデル)

なお、DMDLジェネレータはインフォメーションスキーマ 1 を利用してメタデータを分析しています。

1

http://dev.mysql.com/doc/refman/5.1/ja/information-schema.html

テーブル定義 (レコードモデル)

MySQLに定義されたテーブルごとに、DMDLのレコードモデルを生成します。また、テーブルのカラムごとにプロパティが定義されます。

それぞれの名前は、次のような規則でDMDLでの名前に変換されます。

名前の先頭と末尾にくる全てのアンダースコアを取り除く

2つ以上連続するアンダースコアを単一のアンダースコアに読み替える

全ての文字を小文字にする

たとえば、テーブル _TX__HELLO_WORLD からは、レコードモデル tx_hello_world を生成します。

Caution

上記の変換によってDMDLでの名前が重複してしまう場合、エラーとなります。

カラムに指定できる型と、DMDLでの表現は以下の通りです。

カラムの型とDMDLでの型

MySQLでのデータ型

対応するDMDLの型

TINYINT

BYTE

SMALLINT

SHORT

INT

INT

BIGINT

LONG

DECIMAL

DECIMAL

FLOAT

FLOAT

DOUBLE

DOUBLE

DATE

DATE

DATETIME

DATETIME

TIMESTAMP

DATETIME

CHAR

TEXT

VARCHAR

TEXT

TINYTEXT

TEXT

TEXT

TEXT

MEDIUMTEXT

TEXT

LONGTEXT

TEXT

たとえば、以下のようなテーブルについて考えます。

CREATE TABLE TABLE_EXAMPLE (
    SID              BIGINT        PRIMARY KEY AUTO_INCREMENT,
    VERSION_NO       BIGINT,
    RGST_DATETIME    DATETIME,
    UPDT_DATETIME    DATETIME,
    NAME             VARCHAR(255),
    VALUE            INT
) engine=InnoDB;

上記のテーブルから生成されるレコードモデルの構造は次のような形です。

table_example = {
    sid : LONG;
    version_no : LONG;
    rgst_datetime : DATETIME;
    updt_datetime : DATETIME;
    name : TEXT;
    value : INT;
};

ビュー定義 (結合モデル)

2つのテーブルを結合した「結合モデル」を生成するには、MySQLにテーブルやビューの結合を行うようなビューを登録します。

このビューは、次のような文で生成されたものである必要があります。

2つのテーブルやビューとで、等価内部結合を行っている

SELECT句で結合元のカラムを、演算を行わずにそのまま 2 指定しているおり、それぞれにはテーブル名またはエイリアスが付与されている 3 (t1.SIDなど)

等価結合条件以外のWHERE句が存在しない

2

ここでは演算を行えません。たとえば、「t1.SID + 1」などのようには書けません

3

2つの結合元で同じカラム名が存在しない場合は省略できます

たとえば、以下のような文で作成されたビューから、結合モデルを作成できます。

CREATE VIEW JOIN_EXAMPLE AS
SELECT
    t1.SID AS SID1,
    t2.SID AS SID2,
    t1.VALUE AS VALUE
FROM TABLE_EXAMPLE1 t1, TABLE_EXAMPLE2 t2
WHERE
    t1.VALUE = t2.VALUE;

上記のビューから生成される結合モデルの構造は次のような形です。

joined join_example = table_example1 -> {
    sid -> sid1;
    value -> value;
} % value + table_example2 -> {
    sid -> sid2;
    value -> value;
} % value;

ビュー定義 (集計モデル)

テーブルをグループ化して集計した結果のデータモデル(集計モデル)を生成するには、MySQLにテーブルやビューの集計を行うようなビューを登録します。

このビューは、次のような文で生成されたものである必要があります。

あらゆる結合を行っていない

GROUP BY句でグループ化カラムを指定している

GROUP BY句で指定した全てのカラムは、演算を行わずにSELECT句に指定している

SELECT句に指定する式は、演算を行わないカラムか、集計のみを行ったカラムのみ

WHERE句が存在しない

たとえば、以下のような文で作成されたビューから、集計モデルクラスを作成できます。

CREATE VIEW SUMMARIZE_EXAMPLE AS
SELECT
    NAME AS NAME,
    SUM(VALUE) AS VALUE,
    COUNT(SID) AS SIZE
FROM TABLE_EXAMPLE
GROUP BY NAME;

上記のビューから生成される集計モデルの構造は次のような形です。

summarized summarize_example = table_example => {
    any name -> name;
    sum value -> value;
    count sid -> size;
} % name;

DMDLジェネレータの実行

MySQLのメタデータからDMDLスクリプトを生成するには、 DMDLジェネレータを利用します。

DMDLの生成

DMDLスクリプトからJavaデータモデルクラスを生成する場合、 Asakusa Frameworkの asakusa-thundergate-dmdl-*.jar の com.asakusafw.dmdl.thundergate.Main [https://docs.asakusafw.com/0.10.3/release/api/com/asakusafw/dmdl/thundergate/Main.html] クラスを次の引数で起動します。

-jdbc      JDBCの設定情報を記載したプロパティファイル
-output    DMDLスクリプトを出力するディレクトリ
-encoding  出力するDMDLスクリプトのエンコーディング (default: UTF-8)
-includes  対象とするテーブル/ビュー名の正規表現パターン (default: 全て)
-excludes  除外とするテーブル/ビュー名の正規表現パターン (default: なし)

また、 -jdbc の引数には、下記のような情報を含むファイルのパスを指定します。このファイルはJavaの *.properties ファイル形式で記述します。

jdbc.driver = <JDBCドライバーのクラス名>
jdbc.url = <接続先のJDBC URL>
jdbc.user = <接続ユーザー名>
jdbc.password = <接続パスワード>
database.name = <接続先データベース名>

キャッシュのサポート

ThunderGateのキャッシュ機能をサポートするデータモデルを生成するには、コマンドライン引数に次の内容を追加します。

-sid_column        System IDのカラム名
-timestamp_column  最終更新時刻のカラム名

初期設定では、ThunderGateはSystem IDのカラム名に SID 、最終更新時刻のカラム名に UPDT_DATETIME を利用しています。そのため、ここでの引数は -sid_column SID -timestamp_column UPDT_DATETIME となります。

削除フラグのサポート

テーブルに定義された削除フラグカラムをキャッシュに利用する場合、コマンドラインの引数に次の内容を追加します。

-delete_flag_column  論理削除フラグのカラム名
-delete_flag_value   論理削除フラグが真(TRUE)となる値

削除フラグのカラムに利用できる型は以下に限られています。それぞれの値は、整数、ダブルクウォートした文字列、または大文字の論理値で指定します。

利用できる型と値

型

値の例

CHAR, VARCHAR

"1", "T", "D", など

TINYINT

1, 0, など

BOOLEAN

TRUE, FALSE

上記の情報は、データベースに対して1組のみ指定できます。テーブルに削除フラグのカラムが定義されていない場合には、それに対応するデータモデルが削除をサポートしません。

Attention

文字列型の値には、かならず文字列をダブルクウォートで括ってやる必要があります。コマンドラインシェルから文字列型の値を指定する際には '"1"' のようにさらにシングルクウォートで括るなどしてください。

生成されるデータモデルの属性

DMDLジェネレータが生成するDMDLスクリプトには、 ThunderGateが利用する様々な属性が付けられています。

以下は、DMDLジェネレータが単純なテーブルに対して生成した DMDLスクリプトの例です。

"テーブルTGCACHE_SOURCE"
@auto_projection
@namespace(value = table)
@thundergate.name(value = "TGCACHE_SOURCE")
@thundergate.primary_key(value = { sid })
@thundergate.cache_support(
    sid = sid,
    timestamp = updt_datetime,
    delete_flag = delete_flag,
    delete_flag_value = "1"
)
tgcache_source = {
    "SID"
    @thundergate.name(value = "SID")
    sid : LONG;
    "VERSION_NO"
    @thundergate.name(value = "VERSION_NO")
    version_no : LONG;
    "RGST_DATETIME"
    @thundergate.name(value = "RGST_DATETIME")
    rgst_datetime : DATETIME;
    "UPDT_DATETIME"
    @thundergate.name(value = "UPDT_DATETIME")
    updt_datetime : DATETIME;
    "CATEGORY"
    @thundergate.name(value = "CATEGORY")
    category : INT;
    "DELETE_FLAG"
    @thundergate.name(value = "DELETE_FLAG")
    delete_flag : TEXT;
};

@thundergate. から始まる属性は、DMDLジェネレータが独自に拡張している属性です。そのため、DMDLジェネレータが生成するDMDLスクリプトからプログラムを生成する際には、 DMDLコンパイラのプラグインの指定に asakusa-thundergate-dmdl-*.jar の指定が必要です。

オリジナル名の属性

データモデルの定義に @thundergate.name(value = "<名前>") を指定すると、データモデルの元になったテーブル名やビュー名を保持させられます。

これらの情報は、Asakusa DSLからThunderGateを利用する際にも利用されます 4 。

4

DbImporterDescription や DbExporterDescription を利用する際に、テーブル名やカラム名などを省略していますが、かわりにここで指定した名前を利用しています。

主キー属性

@thundergate.primary_key(value = {<主キーの一覧>}) を指定すると、主キーとして取り扱われるプロパティの情報を保持させられます。

この情報は、ThunderGateがエクスポート処理を高速化する際になどに利用しています。

射影モデルの登録

DMDLジェネレータが生成するデータモデルには、自動射影の属性 @auto_projection が付けられています。

このため、独自に射影モデルを定義して、DMDLジェネレータが生成したデータモデルと併せてDMDLコンパイラに渡すと、射影モデルを自動的に登録させられます。

自動射影や射影モデルについては、 DMDLユーザーガイド も参考にしてください。

キャッシュサポート

@thundergate.cache_support(...) を指定すると、対象のデータモデルはThunderGateのキャッシュ機能をサポートします。これには以下のような項目を指定できます。

キャッシュサポートの項目

項目

必須

内容

sid

○

System IDに対応するプロパティ名

timestamp

○

最終更新時刻に対応するプロパティ名

delete_flag

×

削除フラグに対応するプロパティ名

delete_flag_value

×

削除フラグが成立する値

Asakusa DSLとThunderGateの連携

この文書では、ThunderGateと連携してデータベースを操作するバッチアプリケーションを Asakusa DSLで記述する方法について紹介します。

ThunderGateについての情報は、 ThunderGateユーザーガイド を参照して下さい。

基本的な連携の方法

Asakusa DSLで定義するジョブフローは、 ThunderGateと連携することで入出力にデータベースのテーブルを利用できます。

Note

単一のジョブフローの中で、インポートとエクスポートの対象にできるデータベースは1つまでです。ただし、 補助インポータ の機能を利用すると、制限つきで複数のデータベースからインポートできます。

データベースのテーブルからインポートする

ThunderGateと連携してデータベースのテーブルからデータをインポートする場合、 DbImporterDescription 1 クラスのサブクラスを作成して必要な情報を記述します。このクラスでは、下記のメソッドをオーバーライドします。

String getTargetName()

インポータが使用するターゲット名（データソースを表す識別子）を戻り値に指定します。インポータは実行時に $ASAKUSA_HOME/bulkloader/conf 配下に配置した[ターゲット名]-jdbc.properties に記述されたデータベース接続情報定義ファイルを使用してデータベースに対するアクセスを行います。このファイルの内容については ThunderGateユーザーガイド を参照して下さい。

Class<?> getModelType()

インポータが処理対象とするデータモデルオブジェクトの型を表すクラスを戻り値に指定します。インポータは実行時にデータモデルクラスを作成する元となったテーブル名に対してインポート処理を行います 2 。

LockType getLockType()

インポータの処理時に行われるロックの種類を戻り値に指定します。指定可能なロック種別については BulkLoadImporterDescription.LockType のAPIリファレンスを参照して下さい 3 。

String getWhere()

インポータが利用する抽出条件をSQLの条件式で指定します。指定する文字列はMySQL形式の WHERE 以降の文字列である必要があります。

ここには ${変数名} の形式で、バッチ起動時の引数やあらかじめ宣言された変数を利用できます。利用可能な変数はコンテキストAPIで参照できるものと同様です。詳しくは Asakusa DSLユーザーガイド を参照してください。

DataSize getDataSize()

インポートするデータのおおよそのサイズを指定します。コンパイラはこのデータサイズをヒントに実行計画を作成します。省略された場合にはデータサイズが不明であるという前提で実行計画を作成します。

以下の例では、テーブルから生成したデータモデルクラス Hoge に対応するテーブルの全データをロードして、その際にテーブルロックを取得します。

public class HogeFromDb extends DbImporterDescription {

    public String getTargetName() {
        return "asakusa";
    }

    public Class<?> getModelType() {
        return Hoge.class;
    }

    public LockType getLockType() {
        return LockType.TABLE;
    }
}

以下の例では、バッチ引数で指定した parameter 変数を利用して条件式を指定しています。

public class HogeFromDb extends DbImporterDescription {

    public String getTargetName() {
        return "asakusa";
    }

    public Class<?> getModelType() {
        return Hoge.class;
    }

    public String getWhere() {
        return "NAME = '${parameter}'";
    }

    public LockType getLockType() {
        return LockType.ROW;
    }
}

1

com.asakusafw.vocabulary.bulkloader.DbImporterDescription [https://docs.asakusafw.com/0.10.3/release/api/com/asakusafw/vocabulary/bulkloader/DbImporterDescription.html]

2

DMDLを直接記述してデータモデルクラスを作成している場合、 DbImporterDescription の代わりに BulkLoadImporterDescription 4 を利用して下さい

3

com.asakusafw.vocabulary.bulkloader.BulkLoadImporterDescription.LockType [https://docs.asakusafw.com/0.10.3/release/api/com/asakusafw/vocabulary/bulkloader/BulkLoadImporterDescription.LockType.html]

4

com.asakusafw.vocabulary.bulkloader.BulkLoadImporterDescription [https://docs.asakusafw.com/0.10.3/release/api/com/asakusafw/vocabulary/bulkloader/BulkLoadImporterDescription.html]

データベースのテーブルにエクスポートする

ThunderGateと連携してジョブフローの処理結果をデータベースのテーブルに書き出すには、 DbExporterDescription 5 クラスのサブクラスを作成して必要な情報を記述します。このクラスでは、下記のメソッドをオーバーライドします。

String getTargetName()

エクスポータが使用するターゲット名（データソースを表す識別子）を戻り値に指定します。利用方法はインポータの getTargetName() と同様です。

Class<?> getModelType()

エクスポータが処理対象とするデータモデルオブジェクトの型を表すクラスを戻り値に指定します。エクスポータは実行時にデータモデルクラスを作成する元となったテーブル名に対してエクスポート処理を行います 6 。

以下の例では、テーブルから生成したデータモデルクラス Hoge に対応するテーブルに対して、ジョブフローの処理結果を書き戻します。

public class HogeIntoDb extends DbExporterDescription {

    public Class<?> getModelType() {
        return Hoge.class;
    }
}

5

com.asakusafw.vocabulary.bulkloader.DbExporterDescription [https://docs.asakusafw.com/0.10.3/release/api/com/asakusafw/vocabulary/bulkloader/DbExporterDescription.html]

6

DMDLを直接記述してデータモデルクラスを作成している場合、 DbExporterDescription の代わりに BulkLoadExporterDescription 7 を利用して下さい

7

com.asakusafw.vocabulary.bulkloader.BulkLoadExporterDescription [https://docs.asakusafw.com/0.10.3/release/api/com/asakusafw/vocabulary/bulkloader/BulkLoadExporterDescription.html]

補助インポータ

補助インポータは、１つのジョブフロー中に通常のインポートやエクスポート処理を行うデータベースとは別の、データベースからデータをインポートする際に使用するインポータです。

通常のインポータはデータの更新を前提としてロック取得 (排他制御) の指定を行いますが、補助インポータは指定したテーブルに対してデータを参照のみを行います。つまり、補助インポータを利用すると、「他のデータベースからマスタデータなどの参照データを読み出せる」ということになります 8 。

補助インポータを使用してインポート処理を行うには、 SecondaryImporterDescription 9 を継承したクラス(インポート処理記述クラス)を作成し、必要なメソッドをオーバーライドします。同クラスに指定するメソッドを以下に示します。

String getTargetName()

補助インポータが使用するターゲット名（データソースを表す識別子）を戻り値に指定します。通常のインポータとは異なるターゲット名を指定します。補助インポータ実行時にはターゲット名に対応するデータベース接続情報定義ファイルを配置しておく必要があります。データベース接続情報定義ファイルの定義方法は通常のインポータと同様です。

Class<?> getModelType()

補助インポータが処理対象とするデータモデルオブジェクトの型を表すクラスを戻り値に指定します。利用方法は通常のインポータと同様です。

String getWhere()

補助インポータが利用する抽出条件をSQLの条件式で指定します。利用方法は通常のインポータと同様です。

DataSize getDataSize()

このインポータが取り込むデータサイズの分類を指定します。利用方法は通常のインポータと同様です。

以下の例では、テーブルから生成したデータモデルクラス Foo に対応するテーブルの全データをロードします。また、その時に利用するデータベースは other というターゲット名で指定しています。

以下の例では、テーブルから生成したデータモデルクラス Hoge に対応するテーブルに対して、ジョブフローの処理結果を書き戻します。

/**
 * 補助インポータの動作を定義する。
 */
public class SecondaryImporterExample extends SecondaryImporterDescription {

    @Override
    public String getTargetName() {
        return "other";
    }

    @Override
    public Class<?> getModelType() {
        return Foo.class;
    }

    // 補助インポータはgetLockType()をオーバーライドできない。
}

以下は補助インポータを利用する場合の注意点です。

補助インポータでないインポータのターゲットは、ジョブフロー中で1種類までです

DbImporterDescription を使う場合、 getTargetName() はジョブフロー中で全て同じものにしてください

SecondaryImporterDescription が、 DbImporterDescription と同じターゲット名を指定することは可能です

エクスポータのターゲットは、通常のインポータと同じターゲットにしてください

通常のインポータでターゲットAを指定し、エクスポータと補助インポータにターゲットBを指定、のようなことはできません

通常のインポータを一つも利用しない場合、エクスポータのターゲット名は何を指定してもかまいません

8

これとは逆の「補助エクスポータ」のような仕組みは現在提供していません

9

com.asakusafw.vocabulary.bulkloader.SecondaryImporterDescription [https://docs.asakusafw.com/0.10.3/release/api/com/asakusafw/vocabulary/bulkloader/SecondaryImporterDescription.html]

重複チェック機能

エクスポータの拡張機能で、新しいレコードをテーブルに追加する際に、特定のカラムが同じデータが既にデータベース上にあるかどうかをチェックできます。重複データがデータベース上に既に存在する場合には、そのデータを通常のテーブルには追加せずに、かわりにエラー情報のテーブルに追加します。この機能は既存のレコードに対しては利用できず、 新しいレコードを追加する際にだけ利用できます 。

重複チェックを行う場合、まずは次のようなテーブルが必要です。

正常レコードを登録するテーブル

重複チェック用のカラムがテーブルに存在すること

重複したレコードを登録するエラーテーブル

エラーコードを格納するカラム(CHAR/VARCHAR型)がテーブルに存在すること

この機能の利用方法を、2つのケースに分けて説明します。

正常テーブルよりもエラーテーブルの情報が少ない場合

正常テーブルよりもエラーテーブルの情報が少ない場合に、重複チェックを行う方法を紹介します。このとき、正常テーブルとエラーテーブルは次のような関係であるとします。

正常テーブル

必要な業務情報やシステムカラムを含んでいる

重複チェック用のカラムを含んでいる

エラーテーブル

正常テーブルの一部または全部のカラムが、同じ名前で存在する

さらに、エラーコードを格納するカラムが存在する (正常テーブルに含まれていなくてよい)

つまり、正常テーブルにない情報をエラーテーブルに設定したい場合 10 には、この方法は利用できません。この場合には 正常テーブルとエラーテーブルの構造が大きく異なる場合 を参照して下さい。

重複チェックを行うには DbExporterDescription の代わりに DupCheckDbExporterDescription 11 を継承したエクスポータ記述を作成します。

/**
 * 重複チェックつきエクスポータの動作を定義する (正常テーブル中心)。
 */
public class DupCheckExporterExample1 extends DupCheckDbExporterDescription {

    @Override
    public String getTargetName() {
        return "asakusa";
    }

    @Override
    public Class<?> getModelType() {
        return Hoge.class;
    }

    @Override
    protected Class<?> getNormalModelType() {
        return Hoge.class;
    }

    @Override
    protected Class<?> getErrorModelType() {
        return HogeError.class;
    }

    @Override
    protected List<String> getCheckColumnNames() {
        return Arrays.asList("VALUE");
    }

    @Override
    protected String getErrorCodeColumnName() {
        return "ERR_CODE";
    }

    @Override
    protected String getErrorCodeValue() {
        return "999";
    }
}

それぞれのオーバーライドしたメソッドでは、以下のように設定します。

getTargetName()

エクスポータが使用するターゲット名（データソースを表す識別子）を戻り値に指定します。利用方法は通常のエクスポータやインポータと同様です。

getModelType()

正常テーブルのテーブルモデルクラスを返します。

getNormalModelType()

正常テーブルのテーブルモデルクラスを返します。

getErrorModelType()

エラーテーブルのテーブルモデルクラスを返します。

getCheckColumnNames()

重複チェックを行うカラム名の一覧を返します。この値は、正常テーブルのテーブルモデルに存在するカラムを指定する必要があります。

getErrorCodeColumnName()

エラーコードを格納するカラム名を返します。この値は、エラーテーブルに実際に存在するカラム名である必要があります。

getErrorCodeValue()

重複チェックに失敗した場合に設定されるエラーコードです。この値は重複チェックに失敗したレコードがエラーテーブルに格納される際に、上記「エラーコードを格納するカラム」に自動的に設定されます。

10

エラーコードを格納するカラムだけは、正常テーブルになくても大丈夫です

11

com.asakusafw.vocabulary.bulkloader.DupCheckDbExporterDescription [https://docs.asakusafw.com/0.10.3/release/api/com/asakusafw/vocabulary/bulkloader/DupCheckDbExporterDescription.html]

正常テーブルとエラーテーブルの構造が大きく異なる場合

正常テーブルよりもエラーテーブルの情報が多い場合や、正常テーブルとエラーテーブルの構造が大きく異なる場合には、それらの両方のプロパティを持つデータモデルを予め作成する必要があります。ここでは、そのようなデータモデルを「ユニオンモデル」と仮に呼ぶことにします。

なお、ここで想定する正常テーブルとエラーテーブルは次のような制約があるものとします。

正常テーブル

重複チェック用のカラムを含んでいる

エラーテーブル

エラーコードを格納するカラムが存在する

ユニオンモデルは、上記の2つのテーブルの全てのカラムを持つようなデータ構造である必要があります 12 。

正常テーブルの名前が NORMAL_TABLE, エラーテーブルの名前が ERROR_TABLE である場合、ユニオンモデルはDMDLで次のように記述できます 13 。

union_model = normal_table + error_table;

上記の記述によって、 UnionModel という名前のユニオンモデルを作成できます。

また、ジョブフローやフロー部品では、ユニオンテーブルのテーブルモデルを使って処理を行います。ユニオンテーブルのテーブルモデルをエクスポートする際に、先ほどと同様に DupCheckDbExporterDescription を指定して、次のように書きます。

/**
 * 重複チェックつきエクスポータの動作を定義する (ユニオンモデル)。
 */
public class DupCheckExporterExample2 extends DupCheckDbExporterDescription {

    @Override
    public String getTargetName() {
        return "asakusa";
    }

    @Override
    public Class<?> getModelType() {
        return UnionModel.class;
    }

    @Override
    protected Class<?> getNormalModelType() {
        return NormalTable.class;
    }

    @Override
    protected Class<?> getErrorModelType() {
        return ErrorTable.class;
    }

    @Override
    protected List<String> getCheckColumnNames() {
        return Arrays.asList("VALUE");
    }

    @Override
    protected String getErrorCodeColumnName() {
        return "ERR_CODE";
    }

    @Override
    protected String getErrorCodeValue() {
        return "999";
    }
}

この構造は 正常テーブルよりもエラーテーブルの情報が少ない場合 とほとんど同じですが、メソッド getModelType() の戻り値が異なっています。ジョブフローの出力もここに指定する型(ユニオンモデル)でなくてはならないことに注意して下さい。

全体としては以下のように設定します。

getTargetName()

エクスポータが使用するターゲット名（データソースを表す識別子）を戻り値に指定します。利用方法は通常のエクスポータやインポータと同様です。

getModelType()

ユニオンモデルクラスを返します。

getNormalModelType()

正常テーブルのテーブルモデルクラスを返します。

getErrorModelType()

エラーテーブルのテーブルモデルクラスを返します。

getCheckColumnNames()

重複チェックを行うカラム名の一覧を返します。この値は、正常テーブルのテーブルモデルに存在するカラムを指定する必要があります。

getErrorCodeColumnName()

エラーコードを格納するカラム名を返します。この値は、エラーテーブルに実際に存在するカラム名である必要があります。

getErrorCodeValue()

重複チェックに失敗した場合に設定されるエラーコードです。この値は重複チェックに失敗したレコードがエラーテーブルに格納される際に、上記「エラーコードを格納するカラム」に自動的に設定されます。

この機能で想定するユースケースは、「別システムからの取り込みとクレンジング処理のバッチ」です。

取込みデータの形式をユニオンモデルで表す

正常テーブルは、業務に必要なカラムだけを含める

エラーテーブルは、エラートラッキングに必要なカラムだけを含める

取込みデータをクレンジングして、エラーがあればエラーカラムに情報をセットして、エラーテーブルに情報を書き出す

クレンジングしたデータは、重複チェック機能を使って正常テーブルに情報を書き出す

重複チェックに成功した場合には、必要なカラムだけを正常テーブルに書き出す

重複チェックに失敗した場合には、エラーカラムに「重複エラー」の情報を設定して、エラーテーブルに情報を書き出す

12

より厳密には、「エラーコードカラム」に対応するプロパティはユニオンモデルに不要です

13

DMDLの利用方法は、 DMDLユーザーガイド を参照して下さい

キャッシュ機能

ThunderGateでは、インポート時に前回インポートからの差分のみを転送する「キャッシュ機能」が提供されています。ただし、キャッシュを利用するには主に以下のような制限があります。

条件式 ( getWhere() )を利用できない

ロック ( getLockType() )時に行単位のロックを指定できない

同一のキャッシュを複数のジョブフローで同時に利用できない

詳しい利用方法や、利用時の注意などは Cache for ThunderGate を参照してください。

ThunderGateを利用したアプリケーションのテスト

この文書では、ThunderGateを利用したアプリケーションのテストについて紹介します。 ThunderGateを利用したアプリケーションについては Asakusa DSLとThunderGateの連携 を、テストドライバーの一般的な利用方法については テストドライバーユーザーガイド をそれぞれ参照してください。

テストの流れ

ThunderGateを利用するジョブフローやバッチのテストを行う場合、テストドライバーは関連するデータベース上のテーブルをテスト用に操作します。ジョブフローやバッチの初期データ投入や結果の検証を行う際に、対応する入出力がThunderGateのものであれば、テストドライバーは自動的に一連の操作を行います。

これは次の流れで行います。

テーブルの初期化

テスト対象が利用する入出力全てのテーブルを TRUNCATE TABLE <テーブル名> のコマンドで初期化します。

初期化されるテーブルは、テストで利用するすべてのテーブルです。現在のところ、これを抑制する方法はありません。

この処理はジョブの実行前にまとめて行われます。

初期データの投入

テスト対象が利用する入出力のテーブルに指定したデータセットを、 INSERT INTO <テーブル名> ... のコマンドでそれぞれに挿入します。

利用するデータセットはテストドライバーの prepare(URI) メソッドで指定します。同メソッドの指定がない場合、テーブルには何も挿入しません。

この処理はそれぞれのジョブフローの処理開始前に行われます。そのため、バッチの途中にあるジョブフローを実行する際にそこまでのジョブフローで出力した結果がテーブルに含まれている場合もあります。

結果の取得

テスト対象の実行結果が格納されたテーブルを検証のために、 SELECT ... FROM <テーブル名> のコマンドでそれぞれのテーブルの全内容を取得します。

結果の取得が行われるテーブルは、テストドライバーの verify(...) メソッドが指定されたもののみです。同メソッドの指定がない場合、結果の取得は行いません。

この処理はそれぞれのジョブフローの処理終了後に行われます。つまり、バッチの途中であってもジョブフローが完了するたびに結果の比較が行われ、テストが中断される場合があります。

なお、ジョブフローの入出力には実際のThunderGateによる処理が行われます。テストドライバーが担当するのは上記の3つの処理のみです。

接続先データベースの設定

ThunderGateが利用するデータベースに対してテストドライバーが接続する際、テストドライバーは現在の環境からThunderGateの設定を利用します。このとき利用する設定はJDBCのコネクションに関するもので、 $ASAKUSA_HOME/bulkloader/conf/<ターゲット名>-jdbc.properties に配置されています。

それとは別に、以下に同じ内容のファイルを以下に配置した場合、テストドライバーはそれらを優先して使用します。

クラスパスの <ターゲット名>-jdbc.properties

クラスパスの asakusa-test.properties

上記のファイルが有効になるのは、テストドライバーに特有な以下の操作のみです。

あらゆる処理の前に利用するテーブルをTRUNCATEする

インポートの前にテーブルにデータを流し込む

エクスポート後にテーブルのデータを取り出す

ThunderGateの本来の動作であるインポート処理やエクスポート処理については、上記の設定を利用せずにThunderGate本来の設定を利用します。そのため、上記の設定とThunderGateの設定が乖離している場合、正しく動作しない場合があります。

Warning

上記の設定は、ThunderGateが利用するデータベースに直接テストドライバーからアクセスするためのものです。 ThunderGateを利用するジョブフローをテストする場合、テストの実行中にThunderGateを直接起動します。このとき、ThunderGateは上記の設定 ではなく ThunderGateの設定を優先して利用します。

Note

テスト用に特別な設定を行うケースはほとんどありません。通常は開発環境のThunderGateの設定を利用するようにしてください。

テスト用に特別な設定をするケースは、おそらく開発環境とThunderGateが離れている場合に、開発環境からネットワークを通してデータベースを参照するなどでしょう。