<commit_before>=============================
Asakusa on Spark ユーザガイド
=============================

この文書では、 `Asakusa Framework`_ を使って作成したバッチアプリケーションを `Apache Spark`_ 上で実行する方法について説明します。

..  _`Asakusa Framework`: http://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用のコンパイラを利用します。

..  figure:: attachment/asakusa-spark-sdk.png
    :width: 640px

また、Asakusa DSL Compiler for Sparkで生成したバッチアプリケーションは、従来と同様にYAESSを利用して実行できます。

..  figure:: attachment/asakusa-spark-runtime.png
    :width: 640px

Asakusa DSL
  従来のAsakusa DSLやDMDLで記述したバッチアプリケーションは基本的に変更なしで、Asakusa DSL Compiler for Sparkを利用してSpark向けの実行モジュールを生成することができます。

テスト機構
  従来のAsakusa DSLのテスト方法と同様に、エミュレーションモードを利用してAsakusa DSLのテストを実行することができます。このとき、Sparkは特に利用しません。

アプリケーションの実行
  従来と同様、YAESSを利用してバッチアプリケーションを実行することができます。
  実行環境にMapReduce用のバッチアプリケーションとSpark用のバッチアプリケーションを両方配置して運用することも可能です。

外部システム連携
  Direct I/OやWindGateといった外部システム連携モジュールはSpark向けのバッチアプリケーションでもそのまま利用することができます。
  Direct I/OやWindGateの実行にはHadoopの機能を使用します。Direct I/Oの入出力処理にはMapReduceが使用されるため、MapReduceが動作する環境が併せて必要になります。

..  attention::
    Asakusa on Sparkを利用する上でも外部システム連携機能などにおいて、一部Hadoop MapReduceの機能を利用します。

..  hint::
    Asakusa on Sparkを利用する場合Hadoopクラスタ上でMapReduceとSparkのリソースをまとめて管理できるYARNの利用を推奨しています。

..  _target-platform:

対応プラットフォーム
====================

Hadoopディストリビューション
----------------------------

Asakusa on Sparkは、以下のHadoopディストリビューションと組み合わせた運用環境で動作を検証しています。

..  list-table:: 動作検証プラットフォーム(Hadoopディストリビューション)
    :widths: 3 3 3 2
    :header-rows: 1

    * - Distribution
      - Version
      - OS
      - JDK
    * - Hortonworks Data Platform
      - 2.4 (Apache Hadoop 2.7.1)
      - CentOS 7 (7.1)
      - JDK 8 (1.8.0_60)
    * - MapR
      - 5.0.0 (MRv2)
      - CentOS 6 (6.6)
      - JDK 7 (1.7.0_75)
    * - Amazon EMR
      - AMI 4.3.0
      - Amazon Linux 2015.09
      - JDK 7 (1.7.0_95)

Spark
-----

Asakusa on Spark バージョン |version| は、Spark 1.6.1 で動作を検証しています。

また、Sparkの動作モードとして、YARN cluster mode、および YARN client modeで動作を確認しています。

..  attention::
    Asakusa on Spark バージョン 0.3.0 以降は、 Spark 1.5.2 以前のバージョンでは動作しません。

..  seealso::
    SparkのYARN上での動作モードについては、Sparkのドキュメント `Running Spark on YARN`_ を参照してください。

..  _`Running Spark on YARN`: https://spark.apache.org/docs/latest/running-on-yarn.html

Asakusa Framework 対応バージョン
--------------------------------

Asakusa on Spark バージョン |version| は、Asakusa Framework 0.8.0 以降のバージョンが必要です。

..  warning::
    上記のバージョンより古いバージョンを使用している場合、以降の手順を実施する **前に** 、 :asakusafw:`Asakusa Gradle Plugin マイグレーションガイド <application/gradle-plugin-migration-guide>` を参考にして上記のバージョンにマイグレーションしてください。

Gradle
------

アプリケーションのビルドで使用するGradleのバージョンは ``2.11`` に対応しています。

..  attention::
    Eclipse上で `Shafu`_ を利用している場合、Eclipse設定画面のメニューから :guilabel:`Jinrikisha (人力車)` 選択し、 :guilabel:`Gradleのバージョン` を上記のバージョンに設定してください。

..  _`Shafu`: http://docs.asakusafw.com/jinrikisha/ja/html/shafu.html

非対応機能
~~~~~~~~~~

Asakusa on Sparkは、Asakusa Frameworkが提供する以下の機能には対応していません。

* ThunderGate
* レガシーモジュール
* その他該当バージョンで非推奨となっている機能

リンク
------

各対応プラットフォームへのリンクです。

..  list-table::
    :widths: 3 7
    :header-rows: 1

    * - Product
      - Link
    * - Apache Spark
      - http://spark.apache.org/
    * - Hortonworks Data Platform
      - http://hortonworks.com/hdp/
    * - MapR
      - http://www.mapr.com/
    * - Amazon EMR
      - http://aws.amazon.com/elasticmapreduce/
    * - JDK (Java SE)
      - http://www.oracle.com/technetwork/java/javase/index.html
    * - Gradle
      - http://www.gradle.org/

開発環境の構築
==============

開発環境は従来のAsakusa Frameworkの開発環境をそのまま利用することができます。

新規に開発環境を構築する場合は、以下のドキュメントなどを参考にして開発環境を準備してください。

* :asakusafw:`Asakusa Framework スタートガイド <introduction/start-guide.html>`
* :jinrikisha:`Jinrikisha - Asakusa Framework Starter Package - <index.html>`

アプリケーションの開発
======================

開発環境上で Asakusa Frameworkのバッチアプリケーションを開発し、Spark向けのアプリケーションをビルドする方法を見ていきます。

ここでは、 :asakusafw:`Asakusa Framework スタートガイド <introduction/start-guide.html>` などで使用しているサンプルアプリケーション「カテゴリー別売上金額集計バッチ」をSpark向けにビルドするよう設定します。

Asakusa on Spark Gradle Plugin
------------------------------

Asakusa on Spark Gradle Pluginは、アプリケーションプロジェクトに対してAsakusa on Sparkのさまざまな機能を追加します。

Asakusa on Spark Gradle Pluginを有効にするには、アプリケーションプロジェクトのビルドスクリプト ( :file:`build.gradle` )に対して以下の設定を追加します。

* ``buildscript/dependencis`` ブロックに指定しているAsakusa Gradle Pluginの指定をAsakusa on Spark Gradle Pluginの指定に置き換える。

  * ``group: 'com.asakusafw.spark', name: 'asakusa-spark-gradle', version: '0.3.0'``

* Asakusa on Spark Gradle Pluginを適用する定義を追加する
  
  * ``apply plugin: 'asakusafw-spark'``

以下はAsakusa on Spark Gradle Pluginの設定を追加したビルドスクリプトの例です。

:download:`build.gradle <attachment/build.gradle>`

..  literalinclude:: attachment/build.gradle
    :language: groovy
    :emphasize-lines: 8,15

..  attention::
    Asakusa Framework 0.8.0 以降では、 アプリケーションプロジェクトのテンプレートや一部のサンプルアプリケーションでは上記の設定があらかじめ設定済みになっています。

アプリケーションのビルド
------------------------
`Asakusa on Spark Gradle Plugin`_ を設定した状態で、Gradleタスク :program:`sparkCompileBatchapps` を実行すると、Asakusa DSL Compiler for Sparkを利用し、Spark向けのバッチアプリケーションのビルドを実行します。

..  code-block:: sh
    
    ./gradlew sparkCompileBatchapps

:program:`sparkCompileBatchapps` タスクを実行すると、アプリケーションプロジェクトの :file:`build/spark-batchapps` 配下にビルド済みのバッチアプリケーションが生成されます。

標準の設定では、Asakusa DSL Compiler for Sparkよって生成したバッチアプリケーションは接頭辞に ``spark.`` が付与されます。
例えば、サンプルアプリケーションのバッチID ``example.summarizeSales`` の場合、Spark向けのバッチアプリケーションのバッチIDは ``spark.example.summarizeSales`` となります。
<commit_msg>Revise document for changing batchapp template<commit_after>=============================
Asakusa on Spark ユーザガイド
=============================

この文書では、 `Asakusa Framework`_ を使って作成したバッチアプリケーションを `Apache Spark`_ 上で実行する方法について説明します。

..  _`Asakusa Framework`: http://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用のコンパイラを利用します。

..  figure:: attachment/asakusa-spark-sdk.png
    :width: 640px

また、Asakusa DSL Compiler for Sparkで生成したバッチアプリケーションは、従来と同様にYAESSを利用して実行できます。

..  figure:: attachment/asakusa-spark-runtime.png
    :width: 640px

Asakusa DSL
  従来のAsakusa DSLやDMDLで記述したバッチアプリケーションは基本的に変更なしで、Asakusa DSL Compiler for Sparkを利用してSpark向けの実行モジュールを生成することができます。

テスト機構
  従来のAsakusa DSLのテスト方法と同様に、エミュレーションモードを利用してAsakusa DSLのテストを実行することができます。このとき、Sparkは特に利用しません。

アプリケーションの実行
  従来と同様、YAESSを利用してバッチアプリケーションを実行することができます。
  実行環境にMapReduce用のバッチアプリケーションとSpark用のバッチアプリケーションを両方配置して運用することも可能です。

外部システム連携
  Direct I/OやWindGateといった外部システム連携モジュールはSpark向けのバッチアプリケーションでもそのまま利用することができます。
  Direct I/OやWindGateの実行にはHadoopの機能を使用します。Direct I/Oの入出力処理にはMapReduceが使用されるため、MapReduceが動作する環境が併せて必要になります。

..  attention::
    Asakusa on Sparkを利用する上でも外部システム連携機能などにおいて、一部Hadoop MapReduceの機能を利用します。

..  hint::
    Asakusa on Sparkを利用する場合Hadoopクラスタ上でMapReduceとSparkのリソースをまとめて管理できるYARNの利用を推奨しています。

..  _target-platform:

対応プラットフォーム
====================

Hadoopディストリビューション
----------------------------

Asakusa on Sparkは、以下のHadoopディストリビューションと組み合わせた運用環境で動作を検証しています。

..  list-table:: 動作検証プラットフォーム(Hadoopディストリビューション)
    :widths: 3 3 3 2
    :header-rows: 1

    * - Distribution
      - Version
      - OS
      - JDK
    * - Hortonworks Data Platform
      - 2.4 (Apache Hadoop 2.7.1)
      - CentOS 7 (7.1)
      - JDK 8 (1.8.0_60)
    * - MapR
      - 5.0.0 (MRv2)
      - CentOS 6 (6.6)
      - JDK 7 (1.7.0_75)
    * - Amazon EMR
      - AMI 4.3.0
      - Amazon Linux 2015.09
      - JDK 7 (1.7.0_95)

Spark
-----

Asakusa on Spark バージョン |version| は、Spark 1.6.1 で動作を検証しています。

また、Sparkの動作モードとして、YARN cluster mode、および YARN client modeで動作を確認しています。

..  attention::
    Asakusa on Spark バージョン 0.3.0 以降は、 Spark 1.5.2 以前のバージョンでは動作しません。

..  seealso::
    SparkのYARN上での動作モードについては、Sparkのドキュメント `Running Spark on YARN`_ を参照してください。

..  _`Running Spark on YARN`: https://spark.apache.org/docs/latest/running-on-yarn.html

Asakusa Framework 対応バージョン
--------------------------------

Asakusa on Spark バージョン |version| は、Asakusa Framework 0.8.0 以降のバージョンが必要です。

..  warning::
    上記のバージョンより古いバージョンを使用している場合、以降の手順を実施する **前に** 、 :asakusafw:`Asakusa Gradle Plugin マイグレーションガイド <application/gradle-plugin-migration-guide>` を参考にして上記のバージョンにマイグレーションしてください。

Gradle
------

アプリケーションのビルドで使用するGradleのバージョンは ``2.11`` に対応しています。

..  attention::
    Eclipse上で `Shafu`_ を利用している場合、Eclipse設定画面のメニューから :guilabel:`Jinrikisha (人力車)` 選択し、 :guilabel:`Gradleのバージョン` を上記のバージョンに設定してください。

..  _`Shafu`: http://docs.asakusafw.com/jinrikisha/ja/html/shafu.html

非対応機能
~~~~~~~~~~

Asakusa on Sparkは、Asakusa Frameworkが提供する以下の機能には対応していません。

* ThunderGate
* レガシーモジュール
* その他該当バージョンで非推奨となっている機能

リンク
------

各対応プラットフォームへのリンクです。

..  list-table::
    :widths: 3 7
    :header-rows: 1

    * - Product
      - Link
    * - Apache Spark
      - http://spark.apache.org/
    * - Hortonworks Data Platform
      - http://hortonworks.com/hdp/
    * - MapR
      - http://www.mapr.com/
    * - Amazon EMR
      - http://aws.amazon.com/elasticmapreduce/
    * - JDK (Java SE)
      - http://www.oracle.com/technetwork/java/javase/index.html
    * - Gradle
      - http://www.gradle.org/

開発環境の構築
==============

開発環境は従来のAsakusa Frameworkの開発環境をそのまま利用することができます。

新規に開発環境を構築する場合は、以下のドキュメントなどを参考にして開発環境を準備してください。

* :asakusafw:`Asakusa Framework スタートガイド <introduction/start-guide.html>`
* :jinrikisha:`Jinrikisha - Asakusa Framework Starter Package - <index.html>`

アプリケーションの開発
======================

開発環境上で Asakusa Frameworkのバッチアプリケーションを開発し、Spark向けのアプリケーションをビルドする方法を見ていきます。

ここでは、 :asakusafw:`Asakusa Framework スタートガイド <introduction/start-guide.html>` などで使用しているサンプルアプリケーション「カテゴリー別売上金額集計バッチ」をSpark向けにビルドするよう設定します。

プロジェクトテンプレートのダウンロード
--------------------------------------

Asakusa on Sparkを利用する構成を持つプロジェクトテンプレートは、以下リンクからダウンロードします。

* `asakusa-spark-template-0.3.0.tar.gz <http://www.asakusafw.com/download/gradle-plugin/asakusa-spark-template-0.3.0.tar.gz>`_

また、Asakusa Frameworkの `サンプルプログラム集 (GitHub)`_ では、Asakusa on Sparkを利用する構成を持つサンプルアプリケーションプロジェクトを公開しています。

..  _`サンプルプログラム集 (GitHub)`: http://github.com/asakusafw/asakusafw-examples

Asakusa on Spark Gradle Plugin
------------------------------

Asakusa on Spark Gradle Pluginは、アプリケーションプロジェクトに対してAsakusa on Sparkのさまざまな機能を追加します。

`プロジェクトテンプレートのダウンロード`_ で説明したプロジェクトテンプレートや `サンプルプログラム集 (GitHub)`_ のプロジェクトでは、Asakusa on Spark Gradle Pluginがあらかじめ利用可能になっています。

基本的な構成のみを持つプロジェクトテンプレートからAsakusa on Spark Gradle Pluginを有効にするには、アプリケーションプロジェクトのビルドスクリプト ( :file:`build.gradle` )に対して以下の設定を追加します。

* ``buildscript/dependencis`` ブロックに指定しているAsakusa Gradle Pluginの指定をAsakusa on Spark Gradle Pluginの指定に置き換える。

  * ``group: 'com.asakusafw.spark', name: 'asakusa-spark-gradle', version: '0.3.0'``

* Asakusa on Spark Gradle Pluginを適用する定義を追加する
  
  * ``apply plugin: 'asakusafw-spark'``

以下はAsakusa on Spark Gradle Pluginの設定を追加したビルドスクリプトの例です。

:download:`build.gradle <attachment/build.gradle>`

..  literalinclude:: attachment/build.gradle
    :language: groovy
    :emphasize-lines: 8,15

アプリケーションのビルド
------------------------
`Asakusa on Spark Gradle Plugin`_ を設定した状態で、Gradleタスク :program:`sparkCompileBatchapps` を実行すると、Asakusa DSL Compiler for Sparkを利用し、Spark向けのバッチアプリケーションのビルドを実行します。

..  code-block:: sh
    
    ./gradlew sparkCompileBatchapps

:program:`sparkCompileBatchapps` タスクを実行すると、アプリケーションプロジェクトの :file:`build/spark-batchapps` 配下にビルド済みのバッチアプリケーションが生成されます。

標準の設定では、Asakusa DSL Compiler for Sparkよって生成したバッチアプリケーションは接頭辞に ``spark.`` が付与されます。
例えば、サンプルアプリケーションのバッチID ``example.summarizeSales`` の場合、Spark向けのバッチアプリケーションのバッチIDは ``spark.example.summarizeSales`` となります。

{'fraction_non_alphanumeric': 0.13277843836702338, 'fraction_numerical': 0.012921125644074515, 'mean_word_length': 4.419243986254296, 'pattern_counts': {'":': 0, '<': 14, '<?xml version=': 0, '>': 14, 'https://': 2, 'lorem ipsum': 0, 'www.': 7, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 3, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '3686365', 'n_tokens_mistral': 7779, 'n_tokens_neox': 7053, 'n_words': 740}