fix 404 on japanese image

fix 404 on japanese image

= Chapter 1. OptaPlanner イントロダクション
:awestruct-description: Chapter 1. OptaPlanner イントロダクション
:awestruct-layout: localizedBase
:awestruct-lang: ja
:awestruct-priority: 1.0
:showtitle:

xref:whatIsOptaPlanner[1.1. OptaPlanner とは何ですか？]::
xref:requirements[1.2. 必要なもの]::
xref:whatIsAPlanningProblem[1.3. 計画問題とは？]::
xref:aPlanningProblemIsNPCompleteOrNPHard[1.3.1. 計画問題は NP 完全または NP 困難]:::
xref:aPlanningProblemHasConstraints[1.3.2. 計画問題には制約がある（ハード, ソフト制約）]:::
xref:aPlanningProblemHasAHugeSearchSpace[1.3.3. 計画問題は巨大な探索空間を持つ]:::
xref:downloadAndRunTheExamples[1.4. サンプルのダウンロードと実行]::
xref:getTheReleaseZipAndRunTheExamples[1.4.1. 公開 .zip の入手とサンプルの実行]:::
xref:runTheExamplesInAnIDE[1.4.2. IDE (IntelliJ, Eclipse, NetBeans) でのサンプルの実行]:::
xref:useWithMavenGradleEtc[1.4.3. OptaPlanner を Maven や Gradle, Ivy, Buildr, ANT とともに使う]:::
xref:buildFromSource[1.4.4. OptaPlanner をソースからビルドする]:::
xref:governance[1.5. 管理・運営]::
xref:statusOfOptaPlanner[1.5.1. OptaPlanner のレベルの高さ]:::
xref:backwardsCompatibility[1.5.2. 後方互換性]:::
xref:communityAndSupport[1.5.3. コミュニティとサポート]:::
xref:relationshipWithKie[1.5.4. Drools や jBPM との関係]:::

[]
[[whatIsOptaPlanner]]
== 1.1 OptaPlanner とは何ですか？

image::https://docs.optaplanner.org/6.4.0.Final/optaplanner-docs/html_single/images/Chapter-Planner_introduction/optaPlannerLogo.png[]

*link:https://www.optaplanner.org/[OptaPlanner] は、計画問題の最適解を得る、組み込み可能で軽量な制約充足エンジンです。* 次のようなユースケースを解きます。
////
150907 by Takugo
Source: which optimizes planning problems
Interpreted as: which obtains optimized solutions for planning problems
“問題”を最適化するのではないから。
////

* *従業員シフト勤務計画:* 看護師や修理工などの勤務表作成
* *実施スケジューリング:* 会議, 設備, メンテナンス作業, 広告などのスケジューリング
* *教育時間割り:* 授業, 講座, 試験, 会議プレゼンテーションなどのスケジューリング
* *輸送経路計画:* 荷物および／または人を乗せた乗り物 (トラック, 列車, 船舶, 飛行機など) の計画
* *箱詰め（ビンパッキング）:* コンテナ, トラック, 船舶への積載や倉庫への保管, さらにはクラウドコンピュータのノードなども
* *注文生産スケジューリング:* 自動車組立ライン, 機械処理, 人員作業などの計画
* *在庫削減:* 紙や鋼, カーペットなどの切断で生じる無駄の最少化
* *スポーツにおけるスケジューリング:* フットボールや野球などのリーグ戦計画
////
150907 by Takugo
Source: planning football leagues, baseball leagues, ...
Interpreted as: planning the league games of football, baseball, ...
* *財務最適化:* 投資ポートフォリオの最適化, リスク分散など
////

image::https://docs.optaplanner.org/6.4.0.Final/optaplanner-docs/html_single/images/Chapter-Planner_introduction/useCaseOverview.png[]

あらゆる組織が計画問題に直面しています。製品やサービスは、_制約を受け_ 、限定されたリソース (従業員, 資産, 時間, 金) を使って提供されています。OptaPlanner は、そのような計画を最適化することによって、より少ないリソースでより多くの業務を実行できるようにします。これは、_オペレーションズリサーチ_ 分野の一つである _制約充足プログラミング_ として知られています。
////
150917 Takugo
Source: Constraint Satisfaction Programming
Interpreted as: Constraint Programming (without "satisfaction") = 制約プログラミング, not the meaning of programming problem = 計画問題
////

image::https://docs.optaplanner.org/6.4.0.Final/optaplanner-docs/html_single/images/Chapter-Planner_introduction/whatIsAPlanningProblem.png[]

OptaPlanner の助けがあれば、普通の Java(TM) プログラマーでも制約充足問題を効率よく解くことができます。OptaPlanner の内部では、最適化のためのヒューリスティック法およびメタヒューリスティック法が非常に効率的なスコア計算と組み合わされています。

[[requirements]]
== 1.2. 必要なもの

OptaPlannerは、link:http://www.apache.org/licenses/LICENSE-2.0.html[Apache ソフトウェアライセンス 2.0]の下で配布される _オープンソース・ソフトウェア_ です。このライセンスは、非常に進歩的で、商用目的での再使用を許可しています。link:http://www.apache.org/foundation/license-faq.html#WhatDoesItMEAN[一般向け説明]に目を通してください。

OptaPlanner は、100% 純粋に Java(TM) で作られており、バージョン 1.6 以上のすべての JVM 上で動作します。他の Java(TM) 技術とのxref:integration[統合は非常に簡単]です。OptaPlanner は、xref:useWithMavenGradleEtc[Maven Central Repository]で利用できます。

image::https://docs.optaplanner.org/6.4.0.Final/optaplanner-docs/html_single/images/Chapter-Planner_introduction/compatibility.png[]

[[whatIsAPlanningProblem]]
== 1.3. 計画問題とは？

[[aPlanningProblemIsNPCompleteOrNPHard]]
=== 1.3.1. 計画問題は NP 完全または NP 困難

上に挙げたユースケースはすべて、_おそらく_ 、link:http://en.wikipedia.org/wiki/NP-complete[NP 完全]もしくはそれよりも困難な問題です。NP 完全とは、普通の言葉で表現すると次のような意味です。

* 問題の解を、簡単に、適度な時間内に検証できる。
* 問題の最適解を適度な時間内に見つける確実な方法がない(*)。

.注意
****
(*) 少なくとも、世界中の頭の切れるコンピュータ科学者でさえ、まだ誰もそのような確実な方法を見出せていません。しかし、誰かが 1 つの NP 完全問題について解を一つ見つけたとしたら、その解はすべての NP 完全問題に当てはまることになります。
実際、link:http://en.wikipedia.org/wiki/P_%3D_NP_problem[そのような確実な方法が実在するかどうか]を証明した人には 100 万ドルの懸賞金が与えられることになっています。
****

これは実に恐ろしいことを示唆しています。つまり、次の 2 つの一般的な方法が力不足であるために、自分の抱える問題を解くのが、おそらくは想像以上に困難だということです。

* 総当たりアルゴリズムは、時間がかかりすぎる。（たとえ巧妙に作った変種であっても。）
* 速成のアルゴリズムは、例えば箱詰め（ビンパッキング）において _Largest First 法に従って物を入れる_ アルゴリズムのように、最適解からはほど遠い解を返してしまう。

*OptaPlanner は、先進的な最適化アルゴリズムを使用することによって、そのような計画問題に対して、適度な時間内に良い解を見つけ出します。*

[[aPlanningProblemHasConstraints]]
=== 1.3.2. 計画問題には制約がある（ハード, ソフト制約）

計画問題には、多くの場合、少なくとも次のような 2 つの水準の制約があります。

* _ハード制約 (負値)_ は、違反してはならない。例: _1 人の先生が異なる 2 つの授業で同時に教えることはできない。_
* _ソフト制約 (負値)_ は、避けられる限り、違反してはならない。例: _先生 A は、金曜日の午後に教えたくない。_

次のように、正値の制約を持つ問題もあります。

* 可能な限り、_正値のソフト制約 (または報酬)_ が満足されなければならない。例: _先生 Bは、月曜日の朝に教えたい。_

基本的な問題 (例えば N Queens 問題) には、ハード制約のみ持つものがあります。ハード制約, ミディアム制約, ソフト制約といったように、3 つ以上の水準の制約を持つ問題もあります。

これらの制約によって、各問題の _スコア計算方法_ ( _AKA 適合度関数_ ) が定義されます。一つの問題の複数の解それぞれにスコアを与え、解の優劣を付けることができます。*OptaPlanner のスコア制約は、Java コードのようなオブジェクト指向言語または Drools ルールによって記述されます。* それらのコードは、簡単で、柔軟性と拡張性を有しています。
////
150909 Takugo
Source: AKA --- plain font
Correction assumed: AKA --- italic font
////

[[aPlanningProblemHasAHugeSearchSpace]]
=== 1.3.3. 計画問題は巨大な探索空間を持つ

一つの計画問題には多数の _解_ が存在します。解にはいくつかの種類があります。

* _可能解_ (_possible solution_) は、違反する制約の数を問わずに挙げられるすべての解です。計画問題には、膨大な数の可能解を持つ傾向があります。その解の多くに価値はありません。
////
150911 Takugo
Source: possible solution
Translation: 可能解
専門用語要確認
////
* _実行可能解_ (_feasible solution_) は、ハード制約 (負値) を一つも違反しない解です。実行可能解の数は、可能解の数と相関を持つ傾向にあります。実行可能解が存在しない場合もあります。すべての実行可能解は可能解です。
* _最適解_ (_optimal solution_) は、最高スコアを持つ解です。計画問題には、1 つから数個の最適解を持つ傾向があります。実行可能解が存在せず、最適解が実行可能でない場合であっても、少なくとも 1 つの最適解は必ず存在します。
* _最善解_ (_best solution found_) は、与えられた時間内での実行結果に見出される、最高スコアを持つ解です。見出された最善解は、実行可能である場合が多く、時間が十分に与えられる場合には最適解となります。
可能解の数は、(もしも正確に計算するとしたら、) たとえデータセットが小さくとも、直感に反して膨大になります。サンプルで確認できるように、ほとんどのケースで、既知の宇宙に存在する原子の数の最小値 (10^80^) よりもずっと多くの可能解があります。その最適解を確実に見つけられる方法が存在しないため、いかなる実行方法も、そのすべての可能解の部分集合だけを評価することしかできません。

OptaPlanner は、複数の最適化アルゴリズムを備えており、そのような膨大な数の可能解を効率的に処理します。ユースケース次第で、ある最適化アルゴリズムが他のものよりも良好な性能を示すことがありますが、そのことを事前に知ることは不可能です。*OptaPlanner なら、最適化アルゴリズムを簡単に切り換えられます。* XML またはコードの中のソルバ設定を数行書き替えるだけです。

[[downloadAndRunTheExamples]]
== 1.4. サンプルのダウンロードと実行

[[getTheReleaseZipAndRunTheExamples]]
=== 1.4.1. 公開 .zip の入手とサンプルの実行

今すぐやってみましょう。

{empty}1. link:https://www.optaplanner.org/[OptaPlanner ウェブサイト]から OptaPlanner の公開 .zip をダウンロードします。

{empty}2. 解凍します。

{empty}3. +*examples*+ ディレクトリを開き、スクリプトを実行します。

Linux または Mac:

// [source] //
----
$ cd examples
$ ./runExamples.sh
----

Windows:

// [source] //
----
$ cd examples
$ runExamples.bat
----

// image::https://docs.optaplanner.org/6.4.0.Final/optaplanner-docs/html_single/images/Chapter-Planner_introduction/distributionZip.png[] //
image:https://docs.optaplanner.org/6.4.0.Final/optaplanner-docs/html_single/images/Chapter-Planner_introduction/distributionZip.png[]

サンプル GUI アプリケーションが開きます。サンプルを一つ選択してください。

image::https://docs.optaplanner.org/6.4.0.Final/optaplanner-docs/html_single/images/Chapter-Planner_introduction/plannerExamplesAppScreenshot.png[]

.注意
****
OptaPlanner 自体は GUI に対して依存性を持ちません。OptaPlanner は、デスクトップ上とまったく同様に、サーバやモバイル JVM 上でも動作します。
****

[[runTheExamplesInAnIDE]]
=== 1.4.2. IDE (IntelliJ, Eclipse, NetBeans) でのサンプルの実行

自分の好みの IDE でサンプルを実行するには次のようにします。

{empty}1. IDE を設定します。
* IntelliJ IDEA と NetBeans では、+*examples/sources/pom.xml*+ を新しいプロジェクトとして開きます。そうするだけで、残りは Maven が統合してくれます。
* Eclipse では、ディレクトリ +*examples/sources*+ について新しいプロジェクトを開きます。
** ファイル +*examples/binaries/optaplanner-examples-_version_.jar*+ を除く、ディレクトリ +*bineries*+ および +*examples/binaries*+ に含まれるすべての jar をクラスパスに追加します。
** Java ソースディレクトリ +*src/main/java*+ と Java リソースディレクトリ +*src/main/resources*+ を追加します。
////
150911 Takugo
Source:
Add all the jars to the classpath from the directory binaries and the directory examples/binaries
Interpreted as:
Add all the jars in the directories binaries and examples/binaries to the classpath
////

{empty}2. Run 設定を作成します。
* メインクラス: +org.optaplanner.examples.app.OptaPlannerExamplesApp+
* VM パラメータ (オプション): +-Xmx512M -server+

{empty}3. この Run 設定を実行します。

[[useWithMavenGradleEtc]]
=== 1.4.3. OptaPlanner を Maven や Gradle, Ivy, Buildr, ANT とともに使う

OptaPlanner の jar は、link:http://search.maven.org/#search|ga|1|org.optaplanner[Maven Central Repository] でも利用できます。（link:https://repository.jboss.org/nexus/index.html#nexus-search;gav~org.optaplanner~~~~[JBoss Maven Repository] でも利用できます。）
////
150914 Takugo
Source: central maven repository
Translated: Maven Central Respository
////

Maven を使う場合は、以下のように、プロジェクトの +*pom.xml*+ で +optaplanner-core+ に依存性を追加してください。

----
    <dependency>
      <groupId>org.optaplanner</groupId>
      <artifactId>optaplanner-core</artifactId>
    </dependency>
----

これは、Gradle, Ivy, Buildr についても同様です。最新版は、link:http://search.maven.org/#search|ga|1|org.optaplanner[Maven Central Repository] で確認してください。

他の OptaPlanner モジュールも使用することになる可能性があるため、以下のように、Maven の +dependencyManagement+ で +optaplanner-bom+ をインポートすることを推奨します。こうしておくと、OptaPlanner のバージョン指定は一回だけで済みます。

----
  <dependencyManagement>
    <dependencies>
      <dependency>
        <groupId>org.optaplanner</groupId>
        <artifactId>optaplanner-bom</artifactId>
        <type>pom</type>
        <version>...</version>
        <scope>import</scope>
      </dependency>
      ...
    </dependencies>
  </dependencyManagement>
----

まだ (Ivy なしで) ANT を使用している場合は、ダウンロードした zip 内のディレクトリ +*binaries*+ にあるすべての jar を自分のクラスパスにコピーします。
////
150914 Takugo
Source: copy ... in your class path
Interpreted as: copy ... to your class path
////

.注意
****
ダウンロードした zip 内のディレクトリ +*binaries*+ には、+optaplanner-core+ が実際に使用するよりもはるかに多くの jar を含まれています。+optaplanner-benchmark+ など他のモジュールが使用する jar も含まれています。
////
150914 Takugo
Source: far more jars then
Corrected: far more jars than
////

Maven リポジトリの +*pom.xml*+ ファイルを確認し、(特定のバージョンのための) 特定のモジュールについて、最小の依存性セットを決めてください。
****

[[buildFromSource]]
=== 1.4.4. OptaPlanner をソースからビルドする

OptaPlanner をソースからビルドするのは簡単です。

{empty}1. link:https://help.github.com/articles/set-up-git/[Git を設定]し、GitHub からの +clone optaplanner+ を実行します。(または、link:https://github.com/droolsjbpm/optaplanner/zipball/master[zipball] をダウンロードします。)

----
$ git clone git@github.com:droolsjbpm/optaplanner.git optaplanner
...
----

.注意
****
GitHub アカウントを持っていない場合や、ローカルの Git インストール設定がそのアカウントでなされていない場合は、代わりに次のコマンドを使用して認証問題を回避してください。
----
$ git clone https://github.com/droolsjbpm/optaplanner.git optaplanner
...
----
****

{empty}2. link:http://maven.apache.org/[Maven] を使ってビルドします。

----
$ cd optaplanner
$ mvn clean install -DskipTests
...
----

.注意
****
Maven の初回は、jar をダウンロードする必要があるため、時間がかかるかもしれません。
****

{empty}3. サンプルを実行します。

----
$ cd optaplanner-examples
$ mvn exec:exec
...
----

{empty}4. 好みの IDE でソースを編集します。

{empty}5. オプション: Java プロファイラを使用します。

[[governance]]
== 1.5. 管理・運営

[[statusOfOptaPlanner]]
=== 1.5.1. OptaPlanner のレベルの高さ

OptaPlanner が持つ特長:

* *安定性*: ユニットごとのテスト, 統合環境でのテスト, ストレステストによって非常によくテストされている。
* *信頼性*: 世界中で、製品で使用されている。
* *スケーラビリティ*: サンプルの一つでは、50000 個の変数が扱われ、その 5000 個ごとに、複数の種類の制約とそれを満たす何億ものパターンが扱われている。
* *整備された文書*: 詳細な本マニュアルや多くのサンプルの一つを見てください。

[[backwardsCompatibility]]
=== 1.5.2. 後方互換性

OptaPlanner では、API と実装が分離されます。

* *パブリック API:* パッケージ名前空間 +*org.optaplanner.core.api*+ は、将来のリリースにおいて、100% の後方互換性を有します。
* *Impl クラス:* パッケージ名前空間 +*org.optaplanner.core.impl*+ にあるすべてのクラスには、後方互換性がありません。将来のリリースにおいて変更される可能性があります。link:https://github.com/droolsjbpm/optaplanner/blob/master/optaplanner-distribution/src/main/assembly/filtered-resources/UpgradeFromPreviousVersionRecipe.txt[UpgradeFromPreviousVersionRecipe.txt]と呼ばれるレシピには、新しいバージョンにアップグレードする場合の、各変更内容およびその変更にすばやく対処する方法が記述されています。
* *XML 設定:* XML ソルバ設定は、非パブリック API クラスを使用する必要のある要素を除くすべての要素について、後方互換性を有します。XML ソルバ設定は、パッケージ名前空間 +*org.optaplanner.core.config*+ にあるクラスによって定義されます。

.注意
****
本説明書では、impl クラスもいくつか扱われています。それら文書化された impl クラスは、(本説明書で実験的なものだと明記されない限り) 信頼性があり、安全に使用できます。ただし、それらは、確定的に記述するにはまだ時期尚早なものだと私たちは考えています。
////
150915 Takugo
Source: we're just not entirely comfortable yet to write their signatures in stone
Interpreted as: the impl classes are still subject to changes.
////
****

[[communityAndSupport]]
=== 1.5.3. コミュニティとサポート

ニュースや記事は、link:https://www.optaplanner.org/blog/[私たちのブログ] や Google+ (link:https://plus.google.com/\+OptaPlannerOrg[OptaPlanner], link:https://plus.google.com/\+GeoffreyDeSmet[Geoffrey De Smet])、Twitter (link:https://twitter.com/OptaPlanner[OptaPlanner], link:https://twitter.com/GeoffreyDeSmet[Geoffrey De Smet]) で確認してください。*OptaPlanner が役に立った場合には、そのことについてブログに書いたり Twitter でつぶやいたりして、私たちをご支援ください！*

link:https://www.optaplanner.org/community/forum.html[私たちのコミュニティーの公開フォーラム]での質問やlink:https://issues.jboss.org/browse/PLANNER[課題トラッカー]でのバグ報告、機能要望を歓迎します。GitHub への pull 要求を大いに歓迎し、優先的に扱います！ご自身の改善をオープンソース化すれば、それに対して私たちが加える専門的なチェックやさらなる改良をご自身のために役立てることができます。

Red Hat は、中核となるチームを雇用する形で、OptaPlanner の展開を後援しています。企業向けのサポートやコンサルティングについては、link:https://www.optaplanner.org/community/product.html[BRMS および BPMS 製品] (含 OptaPlanner) を参照するか、link:http://www.redhat.com/en/about/contact/sales[Red Hat へお問い合わせ]ください。

[[relationshipWithKie]]
=== 1.5.4. Drools や jBPM との関係

OptaPlanner は、link:https://www.kiegroup.org/[KIE プロジェクト・グループ]の一部です。KIE グループは、link:https://www.drools.org/[Drools] ルールエンジンと link:https://www.jbpm.org/[jBPM] ワークフローエンジンとともに、定期的に (通常 1〜2 回/月) リリースされます。
////
150916 Takugo
Source: It releases regularly
Interpreted as: The KIE group is released regularly
////

image::https://docs.optaplanner.org/6.4.0.Final/optaplanner-docs/html_single/images/Chapter-Planner_introduction/kieFunctionalityOverview.png[]

Drools を用いたオプションの統合についてより多く知るには、link:https://docs.optaplanner.org/6.4.0.Final/optaplanner-docs/html_single/index.html#architectureOverview[構造の概要]を参照してください。

= Chapter 1. OptaPlanner イントロダクション
:awestruct-description: Chapter 1. OptaPlanner イントロダクション
:awestruct-layout: localizedBase
:awestruct-lang: ja
:awestruct-priority: 1.0
:showtitle:

xref:whatIsOptaPlanner[1.1. OptaPlanner とは何ですか？]::
xref:requirements[1.2. 必要なもの]::
xref:whatIsAPlanningProblem[1.3. 計画問題とは？]::
xref:aPlanningProblemIsNPCompleteOrNPHard[1.3.1. 計画問題は NP 完全または NP 困難]:::
xref:aPlanningProblemHasConstraints[1.3.2. 計画問題には制約がある（ハード, ソフト制約）]:::
xref:aPlanningProblemHasAHugeSearchSpace[1.3.3. 計画問題は巨大な探索空間を持つ]:::
xref:downloadAndRunTheExamples[1.4. サンプルのダウンロードと実行]::
xref:getTheReleaseZipAndRunTheExamples[1.4.1. 公開 .zip の入手とサンプルの実行]:::
xref:runTheExamplesInAnIDE[1.4.2. IDE (IntelliJ, Eclipse, NetBeans) でのサンプルの実行]:::
xref:useWithMavenGradleEtc[1.4.3. OptaPlanner を Maven や Gradle, Ivy, Buildr, ANT とともに使う]:::
xref:buildFromSource[1.4.4. OptaPlanner をソースからビルドする]:::
xref:governance[1.5. 管理・運営]::
xref:statusOfOptaPlanner[1.5.1. OptaPlanner のレベルの高さ]:::
xref:backwardsCompatibility[1.5.2. 後方互換性]:::
xref:communityAndSupport[1.5.3. コミュニティとサポート]:::
xref:relationshipWithKie[1.5.4. Drools や jBPM との関係]:::

[]
[[whatIsOptaPlanner]]
== 1.1 OptaPlanner とは何ですか？

image::https://docs.optaplanner.org/6.4.0.Final/optaplanner-docs/html_single/images/Chapter-Planner_introduction/optaPlannerLogo.png[]

*link:https://www.optaplanner.org/[OptaPlanner] は、計画問題の最適解を得る、組み込み可能で軽量な制約充足エンジンです。* 次のようなユースケースを解きます。
////
150907 by Takugo
Source: which optimizes planning problems
Interpreted as: which obtains optimized solutions for planning problems
“問題”を最適化するのではないから。
////

* *従業員シフト勤務計画:* 看護師や修理工などの勤務表作成
* *実施スケジューリング:* 会議, 設備, メンテナンス作業, 広告などのスケジューリング
* *教育時間割り:* 授業, 講座, 試験, 会議プレゼンテーションなどのスケジューリング
* *輸送経路計画:* 荷物および／または人を乗せた乗り物 (トラック, 列車, 船舶, 飛行機など) の計画
* *箱詰め（ビンパッキング）:* コンテナ, トラック, 船舶への積載や倉庫への保管, さらにはクラウドコンピュータのノードなども
* *注文生産スケジューリング:* 自動車組立ライン, 機械処理, 人員作業などの計画
* *在庫削減:* 紙や鋼, カーペットなどの切断で生じる無駄の最少化
* *スポーツにおけるスケジューリング:* フットボールや野球などのリーグ戦計画
////
150907 by Takugo
Source: planning football leagues, baseball leagues, ...
Interpreted as: planning the league games of football, baseball, ...
* *財務最適化:* 投資ポートフォリオの最適化, リスク分散など
////

image::https://docs.optaplanner.org/6.4.0.Final/optaplanner-docs/html_single/images/Chapter-Planner_introduction/useCaseOverview.png[]

あらゆる組織が計画問題に直面しています。製品やサービスは、_制約を受け_ 、限定されたリソース (従業員, 資産, 時間, 金) を使って提供されています。OptaPlanner は、そのような計画を最適化することによって、より少ないリソースでより多くの業務を実行できるようにします。これは、_オペレーションズリサーチ_ 分野の一つである _制約充足プログラミング_ として知られています。
////
150917 Takugo
Source: Constraint Satisfaction Programming
Interpreted as: Constraint Programming (without "satisfaction") = 制約プログラミング, not the meaning of programming problem = 計画問題
////

image::https://docs.optaplanner.org/6.4.0.Final/optaplanner-docs/html_single/images/Chapter-Planner_introduction/whatIsAPlanningProblem.png[]

OptaPlanner の助けがあれば、普通の Java(TM) プログラマーでも制約充足問題を効率よく解くことができます。OptaPlanner の内部では、最適化のためのヒューリスティック法およびメタヒューリスティック法が非常に効率的なスコア計算と組み合わされています。

[[requirements]]
== 1.2. 必要なもの

OptaPlannerは、link:http://www.apache.org/licenses/LICENSE-2.0.html[Apache ソフトウェアライセンス 2.0]の下で配布される _オープンソース・ソフトウェア_ です。このライセンスは、非常に進歩的で、商用目的での再使用を許可しています。link:http://www.apache.org/foundation/license-faq.html#WhatDoesItMEAN[一般向け説明]に目を通してください。

OptaPlanner は、100% 純粋に Java(TM) で作られており、バージョン 1.6 以上のすべての JVM 上で動作します。他の Java(TM) 技術とのxref:integration[統合は非常に簡単]です。OptaPlanner は、xref:useWithMavenGradleEtc[Maven Central Repository]で利用できます。

// image::https://docs.optaplanner.org/6.4.0.Final/optaplanner-docs/html_single/images/Chapter-Planner_introduction/compatibility.png[] //
image:images/Chapter-Planner_introduction/compatibility.png[]

[[whatIsAPlanningProblem]]
== 1.3. 計画問題とは？

[[aPlanningProblemIsNPCompleteOrNPHard]]
=== 1.3.1. 計画問題は NP 完全または NP 困難

上に挙げたユースケースはすべて、_おそらく_ 、link:http://en.wikipedia.org/wiki/NP-complete[NP 完全]もしくはそれよりも困難な問題です。NP 完全とは、普通の言葉で表現すると次のような意味です。

* 問題の解を、簡単に、適度な時間内に検証できる。
* 問題の最適解を適度な時間内に見つける確実な方法がない(*)。

.注意
****
(*) 少なくとも、世界中の頭の切れるコンピュータ科学者でさえ、まだ誰もそのような確実な方法を見出せていません。しかし、誰かが 1 つの NP 完全問題について解を一つ見つけたとしたら、その解はすべての NP 完全問題に当てはまることになります。
実際、link:http://en.wikipedia.org/wiki/P_%3D_NP_problem[そのような確実な方法が実在するかどうか]を証明した人には 100 万ドルの懸賞金が与えられることになっています。
****

これは実に恐ろしいことを示唆しています。つまり、次の 2 つの一般的な方法が力不足であるために、自分の抱える問題を解くのが、おそらくは想像以上に困難だということです。

* 総当たりアルゴリズムは、時間がかかりすぎる。（たとえ巧妙に作った変種であっても。）
* 速成のアルゴリズムは、例えば箱詰め（ビンパッキング）において _Largest First 法に従って物を入れる_ アルゴリズムのように、最適解からはほど遠い解を返してしまう。

*OptaPlanner は、先進的な最適化アルゴリズムを使用することによって、そのような計画問題に対して、適度な時間内に良い解を見つけ出します。*

[[aPlanningProblemHasConstraints]]
=== 1.3.2. 計画問題には制約がある（ハード, ソフト制約）

計画問題には、多くの場合、少なくとも次のような 2 つの水準の制約があります。

* _ハード制約 (負値)_ は、違反してはならない。例: _1 人の先生が異なる 2 つの授業で同時に教えることはできない。_
* _ソフト制約 (負値)_ は、避けられる限り、違反してはならない。例: _先生 A は、金曜日の午後に教えたくない。_

次のように、正値の制約を持つ問題もあります。

* 可能な限り、_正値のソフト制約 (または報酬)_ が満足されなければならない。例: _先生 Bは、月曜日の朝に教えたい。_

基本的な問題 (例えば N Queens 問題) には、ハード制約のみ持つものがあります。ハード制約, ミディアム制約, ソフト制約といったように、3 つ以上の水準の制約を持つ問題もあります。

これらの制約によって、各問題の _スコア計算方法_ ( _AKA 適合度関数_ ) が定義されます。一つの問題の複数の解それぞれにスコアを与え、解の優劣を付けることができます。*OptaPlanner のスコア制約は、Java コードのようなオブジェクト指向言語または Drools ルールによって記述されます。* それらのコードは、簡単で、柔軟性と拡張性を有しています。
////
150909 Takugo
Source: AKA --- plain font
Correction assumed: AKA --- italic font
////

[[aPlanningProblemHasAHugeSearchSpace]]
=== 1.3.3. 計画問題は巨大な探索空間を持つ

一つの計画問題には多数の _解_ が存在します。解にはいくつかの種類があります。

* _可能解_ (_possible solution_) は、違反する制約の数を問わずに挙げられるすべての解です。計画問題には、膨大な数の可能解を持つ傾向があります。その解の多くに価値はありません。
////
150911 Takugo
Source: possible solution
Translation: 可能解
専門用語要確認
////
* _実行可能解_ (_feasible solution_) は、ハード制約 (負値) を一つも違反しない解です。実行可能解の数は、可能解の数と相関を持つ傾向にあります。実行可能解が存在しない場合もあります。すべての実行可能解は可能解です。
* _最適解_ (_optimal solution_) は、最高スコアを持つ解です。計画問題には、1 つから数個の最適解を持つ傾向があります。実行可能解が存在せず、最適解が実行可能でない場合であっても、少なくとも 1 つの最適解は必ず存在します。
* _最善解_ (_best solution found_) は、与えられた時間内での実行結果に見出される、最高スコアを持つ解です。見出された最善解は、実行可能である場合が多く、時間が十分に与えられる場合には最適解となります。
可能解の数は、(もしも正確に計算するとしたら、) たとえデータセットが小さくとも、直感に反して膨大になります。サンプルで確認できるように、ほとんどのケースで、既知の宇宙に存在する原子の数の最小値 (10^80^) よりもずっと多くの可能解があります。その最適解を確実に見つけられる方法が存在しないため、いかなる実行方法も、そのすべての可能解の部分集合だけを評価することしかできません。

OptaPlanner は、複数の最適化アルゴリズムを備えており、そのような膨大な数の可能解を効率的に処理します。ユースケース次第で、ある最適化アルゴリズムが他のものよりも良好な性能を示すことがありますが、そのことを事前に知ることは不可能です。*OptaPlanner なら、最適化アルゴリズムを簡単に切り換えられます。* XML またはコードの中のソルバ設定を数行書き替えるだけです。

[[downloadAndRunTheExamples]]
== 1.4. サンプルのダウンロードと実行

[[getTheReleaseZipAndRunTheExamples]]
=== 1.4.1. 公開 .zip の入手とサンプルの実行

今すぐやってみましょう。

{empty}1. link:https://www.optaplanner.org/[OptaPlanner ウェブサイト]から OptaPlanner の公開 .zip をダウンロードします。

{empty}2. 解凍します。

{empty}3. +*examples*+ ディレクトリを開き、スクリプトを実行します。

Linux または Mac:

// [source] //
----
$ cd examples
$ ./runExamples.sh
----

Windows:

// [source] //
----
$ cd examples
$ runExamples.bat
----

// image::https://docs.optaplanner.org/6.4.0.Final/optaplanner-docs/html_single/images/Chapter-Planner_introduction/distributionZip.png[] //
image:https://docs.optaplanner.org/6.4.0.Final/optaplanner-docs/html_single/images/Chapter-Planner_introduction/distributionZip.png[]

サンプル GUI アプリケーションが開きます。サンプルを一つ選択してください。

image::https://docs.optaplanner.org/6.4.0.Final/optaplanner-docs/html_single/images/Chapter-Planner_introduction/plannerExamplesAppScreenshot.png[]

.注意
****
OptaPlanner 自体は GUI に対して依存性を持ちません。OptaPlanner は、デスクトップ上とまったく同様に、サーバやモバイル JVM 上でも動作します。
****

[[runTheExamplesInAnIDE]]
=== 1.4.2. IDE (IntelliJ, Eclipse, NetBeans) でのサンプルの実行

自分の好みの IDE でサンプルを実行するには次のようにします。

{empty}1. IDE を設定します。
* IntelliJ IDEA と NetBeans では、+*examples/sources/pom.xml*+ を新しいプロジェクトとして開きます。そうするだけで、残りは Maven が統合してくれます。
* Eclipse では、ディレクトリ +*examples/sources*+ について新しいプロジェクトを開きます。
** ファイル +*examples/binaries/optaplanner-examples-_version_.jar*+ を除く、ディレクトリ +*bineries*+ および +*examples/binaries*+ に含まれるすべての jar をクラスパスに追加します。
** Java ソースディレクトリ +*src/main/java*+ と Java リソースディレクトリ +*src/main/resources*+ を追加します。
////
150911 Takugo
Source:
Add all the jars to the classpath from the directory binaries and the directory examples/binaries
Interpreted as:
Add all the jars in the directories binaries and examples/binaries to the classpath
////

{empty}2. Run 設定を作成します。
* メインクラス: +org.optaplanner.examples.app.OptaPlannerExamplesApp+
* VM パラメータ (オプション): +-Xmx512M -server+

{empty}3. この Run 設定を実行します。

[[useWithMavenGradleEtc]]
=== 1.4.3. OptaPlanner を Maven や Gradle, Ivy, Buildr, ANT とともに使う

OptaPlanner の jar は、link:http://search.maven.org/#search|ga|1|org.optaplanner[Maven Central Repository] でも利用できます。（link:https://repository.jboss.org/nexus/index.html#nexus-search;gav~org.optaplanner~~~~[JBoss Maven Repository] でも利用できます。）
////
150914 Takugo
Source: central maven repository
Translated: Maven Central Respository
////

Maven を使う場合は、以下のように、プロジェクトの +*pom.xml*+ で +optaplanner-core+ に依存性を追加してください。

----
    <dependency>
      <groupId>org.optaplanner</groupId>
      <artifactId>optaplanner-core</artifactId>
    </dependency>
----

これは、Gradle, Ivy, Buildr についても同様です。最新版は、link:http://search.maven.org/#search|ga|1|org.optaplanner[Maven Central Repository] で確認してください。

他の OptaPlanner モジュールも使用することになる可能性があるため、以下のように、Maven の +dependencyManagement+ で +optaplanner-bom+ をインポートすることを推奨します。こうしておくと、OptaPlanner のバージョン指定は一回だけで済みます。

----
  <dependencyManagement>
    <dependencies>
      <dependency>
        <groupId>org.optaplanner</groupId>
        <artifactId>optaplanner-bom</artifactId>
        <type>pom</type>
        <version>...</version>
        <scope>import</scope>
      </dependency>
      ...
    </dependencies>
  </dependencyManagement>
----

まだ (Ivy なしで) ANT を使用している場合は、ダウンロードした zip 内のディレクトリ +*binaries*+ にあるすべての jar を自分のクラスパスにコピーします。
////
150914 Takugo
Source: copy ... in your class path
Interpreted as: copy ... to your class path
////

.注意
****
ダウンロードした zip 内のディレクトリ +*binaries*+ には、+optaplanner-core+ が実際に使用するよりもはるかに多くの jar を含まれています。+optaplanner-benchmark+ など他のモジュールが使用する jar も含まれています。
////
150914 Takugo
Source: far more jars then
Corrected: far more jars than
////

Maven リポジトリの +*pom.xml*+ ファイルを確認し、(特定のバージョンのための) 特定のモジュールについて、最小の依存性セットを決めてください。
****

[[buildFromSource]]
=== 1.4.4. OptaPlanner をソースからビルドする

OptaPlanner をソースからビルドするのは簡単です。

{empty}1. link:https://help.github.com/articles/set-up-git/[Git を設定]し、GitHub からの +clone optaplanner+ を実行します。(または、link:https://github.com/droolsjbpm/optaplanner/zipball/master[zipball] をダウンロードします。)

----
$ git clone git@github.com:droolsjbpm/optaplanner.git optaplanner
...
----

.注意
****
GitHub アカウントを持っていない場合や、ローカルの Git インストール設定がそのアカウントでなされていない場合は、代わりに次のコマンドを使用して認証問題を回避してください。
----
$ git clone https://github.com/droolsjbpm/optaplanner.git optaplanner
...
----
****

{empty}2. link:http://maven.apache.org/[Maven] を使ってビルドします。

----
$ cd optaplanner
$ mvn clean install -DskipTests
...
----

.注意
****
Maven の初回は、jar をダウンロードする必要があるため、時間がかかるかもしれません。
****

{empty}3. サンプルを実行します。

----
$ cd optaplanner-examples
$ mvn exec:exec
...
----

{empty}4. 好みの IDE でソースを編集します。

{empty}5. オプション: Java プロファイラを使用します。

[[governance]]
== 1.5. 管理・運営

[[statusOfOptaPlanner]]
=== 1.5.1. OptaPlanner のレベルの高さ

OptaPlanner が持つ特長:

* *安定性*: ユニットごとのテスト, 統合環境でのテスト, ストレステストによって非常によくテストされている。
* *信頼性*: 世界中で、製品で使用されている。
* *スケーラビリティ*: サンプルの一つでは、50000 個の変数が扱われ、その 5000 個ごとに、複数の種類の制約とそれを満たす何億ものパターンが扱われている。
* *整備された文書*: 詳細な本マニュアルや多くのサンプルの一つを見てください。

[[backwardsCompatibility]]
=== 1.5.2. 後方互換性

OptaPlanner では、API と実装が分離されます。

* *パブリック API:* パッケージ名前空間 +*org.optaplanner.core.api*+ は、将来のリリースにおいて、100% の後方互換性を有します。
* *Impl クラス:* パッケージ名前空間 +*org.optaplanner.core.impl*+ にあるすべてのクラスには、後方互換性がありません。将来のリリースにおいて変更される可能性があります。link:https://github.com/droolsjbpm/optaplanner/blob/master/optaplanner-distribution/src/main/assembly/filtered-resources/UpgradeFromPreviousVersionRecipe.txt[UpgradeFromPreviousVersionRecipe.txt]と呼ばれるレシピには、新しいバージョンにアップグレードする場合の、各変更内容およびその変更にすばやく対処する方法が記述されています。
* *XML 設定:* XML ソルバ設定は、非パブリック API クラスを使用する必要のある要素を除くすべての要素について、後方互換性を有します。XML ソルバ設定は、パッケージ名前空間 +*org.optaplanner.core.config*+ にあるクラスによって定義されます。

.注意
****
本説明書では、impl クラスもいくつか扱われています。それら文書化された impl クラスは、(本説明書で実験的なものだと明記されない限り) 信頼性があり、安全に使用できます。ただし、それらは、確定的に記述するにはまだ時期尚早なものだと私たちは考えています。
////
150915 Takugo
Source: we're just not entirely comfortable yet to write their signatures in stone
Interpreted as: the impl classes are still subject to changes.
////
****

[[communityAndSupport]]
=== 1.5.3. コミュニティとサポート

ニュースや記事は、link:https://www.optaplanner.org/blog/[私たちのブログ] や Google+ (link:https://plus.google.com/\+OptaPlannerOrg[OptaPlanner], link:https://plus.google.com/\+GeoffreyDeSmet[Geoffrey De Smet])、Twitter (link:https://twitter.com/OptaPlanner[OptaPlanner], link:https://twitter.com/GeoffreyDeSmet[Geoffrey De Smet]) で確認してください。*OptaPlanner が役に立った場合には、そのことについてブログに書いたり Twitter でつぶやいたりして、私たちをご支援ください！*

link:https://www.optaplanner.org/community/forum.html[私たちのコミュニティーの公開フォーラム]での質問やlink:https://issues.jboss.org/browse/PLANNER[課題トラッカー]でのバグ報告、機能要望を歓迎します。GitHub への pull 要求を大いに歓迎し、優先的に扱います！ご自身の改善をオープンソース化すれば、それに対して私たちが加える専門的なチェックやさらなる改良をご自身のために役立てることができます。

Red Hat は、中核となるチームを雇用する形で、OptaPlanner の展開を後援しています。企業向けのサポートやコンサルティングについては、link:https://www.optaplanner.org/community/product.html[BRMS および BPMS 製品] (含 OptaPlanner) を参照するか、link:http://www.redhat.com/en/about/contact/sales[Red Hat へお問い合わせ]ください。

[[relationshipWithKie]]
=== 1.5.4. Drools や jBPM との関係

OptaPlanner は、link:https://www.kiegroup.org/[KIE プロジェクト・グループ]の一部です。KIE グループは、link:https://www.drools.org/[Drools] ルールエンジンと link:https://www.jbpm.org/[jBPM] ワークフローエンジンとともに、定期的に (通常 1〜2 回/月) リリースされます。
////
150916 Takugo
Source: It releases regularly
Interpreted as: The KIE group is released regularly
////

image::https://docs.optaplanner.org/6.4.0.Final/optaplanner-docs/html_single/images/Chapter-Planner_introduction/kieFunctionalityOverview.png[]

Drools を用いたオプションの統合についてより多く知るには、link:https://docs.optaplanner.org/6.4.0.Final/optaplanner-docs/html_single/index.html#architectureOverview[構造の概要]を参照してください。


Update 2017-04-16-Predict-Survival-Propensity-of-Titanic-Passengers.adoc

// = Your Blog title
// See https://hubpress.gitbooks.io/hubpress-knowledgebase/content/ for information about the parameters.
// :hp-image: /covers/cover.png
// :published_at: 2019-01-31
// :hp-tags: HubPress, Blog, Open_Source,
// :hp-alt-title: My English Title

= Titanic: Learning Data Science with RStudio
:hp-alt-title: Predict Survival Propensity of Titanic Passengers
:hp-tags: Blog, Open_Source, Machine_Learning, Analytics, Data_Science
:icons: image

So we are aspiring data scientists and want to dip our toes into link:http://rmarkdown.rstudio.com/[RStudio]. How do we get started? We dive into the into the waters of the link:https://www.kaggle.com/c/titanic[Kaggle Titanic "Competition"], of course!

Our objective:

* learn how to think about the competition from a data science perspective
* get somewhat comfortable with RStudio
* predict whether or not a passenger would survive the sinking of the link:https://en.wikipedia.org/wiki/RMS_Titanic[RMS Titanic]
* enter a Kaggle submission file for evaluation
* profit!

== Kaggle Basics

Kaggle is a community of data scientists and a platform for facilitating data science journeys. One way to participate, is by entering data science competitions. Similar to other competitions, Kaggle provides two Titanic datasets containing passenger attributes:

* a _training set_, complete with the outcome (target) variable for training our predictive model(s)
* a _test set_, for predicting the unknown outcome variable based on the passenger attributes provided in both datasets.

After training and validating our predictive model(s), we can then enter the submission file to Kaggle for evaluation. As we iterate, we can submit more files and assess our progress on the leaderboard. Subtle model improvements can lead to significant leaps on the leaderboard.

[cols="1, 8a"]
|===
|image:/images/icons/tip.png[icon="tip",size="4x",width=56]
|*Data Science Perspective*

We need to use the provided attributes (variables) to train a predictive model, and how does that work? Some variables are correlated with each other. When those variables vary, the correlated variables will also vary to some degree. We need to:

  * maximize the number of explanatory variables: those that are correlated with the outcome variable, and

  * minimize the correlation of explanatory variables to each other (link:https://en.wikipedia.org/wiki/Multicollinearity[multicollinearity]).

In other words, we need to find the fewest quantity of variables that can explain everything that is going on with the outcome that we want to predict.
|===

== Titanic History Lesson

The Titanic was a British passenger liner that sank after colliding with an iceberg in the Atlantic on its maiden voyage en route to New York City. It was the largest ship of its time with 10 decks, 8 of which were for passengers.

There were 2,224 passengers and crew aboard. Of the 1,317 passengers, there were: 324 in First Class (including some of the wealthiest people of the time), 284 in Second Class, and 709 in Third Class. Of these, 869 (66%) were male and 447 (34%) female. There were 107 children aboard, the largest number of which were in Third Class.

The ship had enough lifeboats for about 1,100 passengers, and more than 1,500 died. Due to the "women and children first" protocol, men were disproportionately left aboard. Also, not all lifeboats were completely filled during the evacuation. The 705 surviving passengers were rescued by the RMS Carpathia around 2 hours after the catastrophe.

== Tutorial Approach

We'll approach this project in multiple parts. This is still a work in progress, but roughly speaking it should look like:

. Part 1: Basic Setup
. Part 2: Feature Engineering
. Part 3: Prediction
. Part 4: Conclusion

//[[app-listing]]
//[source,ruby]
//.test.ruby
//----
//----

// = Your Blog title
// See https://hubpress.gitbooks.io/hubpress-knowledgebase/content/ for information about the parameters.
// :hp-image: /covers/cover.png
// :published_at: 2019-01-31
// :hp-tags: HubPress, Blog, Open_Source,
// :hp-alt-title: My English Title

= Titanic: Learning Data Science with RStudio
:hp-alt-title: Predict Survival Propensity of Titanic Passengers
:hp-tags: Blog, Open_Source, Machine_Learning, Analytics, Data_Science
:icons: image

So we are aspiring data scientists and want to dip our toes into link:http://rmarkdown.rstudio.com/[RStudio]. How do we get started? We dive into the into the waters of the link:https://www.kaggle.com/c/titanic[Kaggle Titanic "Competition"], of course!

Our objective:

* learn how to think about the competition from a data science perspective
* get somewhat comfortable with RStudio
* predict whether or not a passenger would survive the sinking of the link:https://en.wikipedia.org/wiki/RMS_Titanic[RMS Titanic]
* enter a Kaggle submission file for evaluation
* profit!

== Kaggle Basics

Kaggle is a community of data scientists and a platform for facilitating data science journeys. One way to participate, is by entering data science competitions. Similar to other competitions, Kaggle provides two Titanic datasets containing passenger attributes:

* a _training set_, complete with the outcome (target) variable for training our predictive model(s)
* a _test set_, for predicting the unknown outcome variable based on the passenger attributes provided in both datasets.

After training and validating our predictive model(s), we can then enter the submission file to Kaggle for evaluation. As we iterate, we can submit more files and assess our progress on the leaderboard. Subtle model improvements can lead to significant leaps on the leaderboard.

[cols="2*"]
|===
|image:/images/icons/tip.png[icon="tip",size="4x",width=56]
|*Data Science Perspective*

|
|We need to use the provided attributes (variables) to train a predictive model, and how does that work? Some variables are correlated with each other. When those variables vary, the correlated variables will also vary to some degree. We need to:

- maximize the number of explanatory variables: those that are correlated with the outcome variable, and
- minimize the correlation of explanatory variables to each other (link:https://en.wikipedia.org/wiki/Multicollinearity[multicollinearity]).

In other words, we need to find the fewest quantity of variables that can explain everything that is going on with the outcome that we want to predict.
|===

== Titanic History Lesson

The Titanic was a British passenger liner that sank after colliding with an iceberg in the Atlantic on its maiden voyage en route to New York City. It was the largest ship of its time with 10 decks, 8 of which were for passengers.

There were 2,224 passengers and crew aboard. Of the 1,317 passengers, there were: 324 in First Class (including some of the wealthiest people of the time), 284 in Second Class, and 709 in Third Class. Of these, 869 (66%) were male and 447 (34%) female. There were 107 children aboard, the largest number of which were in Third Class.

The ship had enough lifeboats for about 1,100 passengers, and more than 1,500 died. Due to the "women and children first" protocol, men were disproportionately left aboard. Also, not all lifeboats were completely filled during the evacuation. The 705 surviving passengers were rescued by the RMS Carpathia around 2 hours after the catastrophe.

== Tutorial Approach

We'll approach this project in multiple parts. This is still a work in progress, but roughly speaking it should look like:

. Part 1: Basic Setup
. Part 2: Feature Engineering
. Part 3: Prediction
. Part 4: Conclusion

//[[app-listing]]
//[source,ruby]
//.test.ruby
//----
//----


// = Your Blog title
// See https://hubpress.gitbooks.io/hubpress-knowledgebase/content/ for information about the parameters.
// :hp-image: /covers/cover.png
// :published_at: 2019-01-31
// :hp-tags: HubPress, Blog, Open_Source,
// :hp-alt-title: My English Title

= Kaggle: Learning from Titanic
:hp-alt-title: Predict Survival Propensity of Titanic Passengers
:hp-tags: Blog, Open_Source, Machine_Learning, Analytics, Data_Science

So we are aspiring data scienctists and want to dip our toes into the the water. How do we get started using link:http://rmarkdown.rstudio.com/[RStudio]? We dive into the into the waters of the link:https://www.kaggle.com/c/titanic[Kaggle Titanic Starting "Competition"], of course!

Our objective:

* learn how to think about the competition from a data science perspective
* predict whether or not a passenger would survive the sinking of the link:https://en.wikipedia.org/wiki/RMS_Titanic[RMS Titanic]
* enter a Kaggle submission file for evaluation
* profit!

== Kaggle Basics

Kaggle is a community of data scientists and a platform for facilitating data science journeys. To participate, you may enter data science competitions. Kaggle provides two datasets for the Titanic competition containing passenger attributes:

* a training set, complete with the outcome (target) variable for training our predictive model.
* a test set, for predicting the unknown outcome variable based on the passenger attributes provided in both datasets.

After training and validating our predictive model, we then enter the submission file to Kaggle for evaluation.

//[icon="/images/note.png"]
[NOTE]
.*Think like a Data Scientist*
=====================================
We need to use the provided attributes (variables) to train a predictive model, but how does that work?

- Some variables are correlated with each other. When those variables vary, the other variables will also vary to some degree
- We need to maximize the number of explanatory variables: those that are correlated with the outcome variable and
- minimize the correlation of explanatory variables to each other (link:https://en.wikipedia.org/wiki/Multicollinearity[multicollinearity]).

In other words, we need to find the fewest quantity of variables that can explain everything that is going on with the outcome that we want to predict.
=====================================

== Quick History Lesson

The Titanic was a British passenger liner that sank after colliding with an iceberg in the Atlantic on its maiden voyage enroute to New York City. It was the largest ship of its time with 10 decks, 8 of which were for passengers. There were approximately 2200 passengers and crew aboard.

Of the 1,317 passenger, there were: 324 in First Class (including some of the wealthiest people of the time), 284 in Second Class, and 709 in Third Class. Of these, 869 (66%) were male and 447 (34%) female. There were 107 children aboard, the largest number of which were in Third Class.

The ship had enough life boats for about 1100 passengers, and more than 1500 died. Due to the "women and children first" protocol, men were disproportionately left aboard. Also, not all lifeboats were completely filled during the evacuation. The 705 surviving passengers were rescued by the RMS Carpathia around 2 hours after the catastrophe.

// = Your Blog title
// See https://hubpress.gitbooks.io/hubpress-knowledgebase/content/ for information about the parameters.
// :hp-image: /covers/cover.png
// :published_at: 2019-01-31
// :hp-tags: HubPress, Blog, Open_Source,
// :hp-alt-title: My English Title

= Kaggle: Learning from Titanic
:hp-alt-title: Predict Survival Propensity of Titanic Passengers
:hp-tags: Blog, Open_Source, Machine_Learning, Analytics, Data_Science

So we are aspiring data scienctists and want to dip our toes into the the water. How do we get started using link:http://rmarkdown.rstudio.com/[RStudio]? We dive into the into the waters of the link:https://www.kaggle.com/c/titanic[Kaggle Titanic Starting "Competition"], of course!

Our objective:

* learn how to think about the competition from a data science perspective
* predict whether or not a passenger would survive the sinking of the link:https://en.wikipedia.org/wiki/RMS_Titanic[RMS Titanic]
* enter a Kaggle submission file for evaluation
* profit!

== Kaggle Basics

Kaggle is a community of data scientists and a platform for facilitating data science journeys. To participate, you may enter data science competitions. Kaggle provides two datasets for the Titanic competition containing passenger attributes:

* a training set, complete with the outcome (target) variable for training our predictive model.
* a test set, for predicting the unknown outcome variable based on the passenger attributes provided in both datasets.

After training and validating our predictive model, we then enter the submission file to Kaggle for evaluation.

//[icon="/images/note.png"]
[NOTE]
.*Think like a Data Scientist*
=====================================
We need to use the provided attributes (variables) to train a predictive model, but how does that work?

- Some variables are correlated with each other. When those variables vary, the other variables will also vary to some degree
- We need to maximize the number of explanatory variables: those that are correlated with the outcome variable and
- minimize the correlation of explanatory variables to each other (link:https://en.wikipedia.org/wiki/Multicollinearity[Multicollinearity]).

In other words, we need to find the fewest quantity of variables that can explain everything that is going on with the outcome that we want to predict.
=====================================

== Quick History Lesson

The Titanic was a British passenger liner that sank after colliding with an iceberg in the Atlantic on its maiden voyage enroute to New York City. It was the largest ship of its time with 10 decks, 8 of which were for passengers. There were approximately 2200 passengers and crew aboard.

Of the 1,317 passenger, there were: 324 in First Class (including some of the wealthiest people of the time), 284 in Second Class, and 709 in Third Class. Of these, 869 (66%) were male and 447 (34%) female. There were 107 children aboard, the largest number of which were in Third Class.

The ship had enough life boats for about 1100 passengers, and more than 1500 died. Due to the "women and children first" protocol, men were disproportionately left aboard. Also, not all lifeboats were completely filled during the evacuation. The 705 surviving passengers were rescued by the RMS Carpathia around 2 hours after the catastrophe.


OP Guide: Additions for ZK failure handling and maintenance

Change-Id: I7754bbda02d46ee812b4f81367aeef416ee38d89
Ref: https://midonet.atlassian.net/browse/MND-202
Signed-off-by: Jan Hilberath <14e793d896ddc8ca6911747228e86464cf420065@midokura.com>

[[midolman_configuration_options]]
= MidoNet Agent (Midolman) configuration options

This section covers all configuration options for the MidoNet Agent.

We don't recommend making changes to the default values, except possibly the
+zookeeper.session_gracetime+ and +agent.datapath.send_buffer_pool_buf_size_kb+
setting values.

[WARNING]
Do not modify the root key, cluster name, or keyspace unless you know what you
are doing.

++++
<?dbhtml stop-chunking?>
++++

== MidoNet behavior after ZooKeeper cluster failure

Nodes running the MidoNet Agent, Midolman, depend on a live ZooKeeper session to
load pieces of a virtual network topology on-demand and watch for updates to
those virtual devices.

When ZooKeeper becomes inaccessible, a MidoNet Agent instance will continue
operating for as long as there's a chance to recover connectivity while keeping
the same ZooKeeper session. The amount of operating time is thus dictated by the
session timeout, which you can control by editing the zookeeper
session_gracetime setting in mn-conf(1).

Once the session expires, the MidoNet Agent will give up and shut itself down,
prompting upstart to re-launch it. If the ZooKeeper connection and session are
recovered within the session_gracetime, MidoNet Agent operation will resume
uneventfully. The MidoNet Agent will learn of all the updates that happened to
the virtual topology while it was disconnected and will update its internal
state and flow tables accordingly.

While the MidoNet Agent is running disconnected from ZooKeeper, waiting for the
session to come back, traffic will still be processed, but with reduced
functionality, as follows:

* The MidoNet Agent will not see updates to the virtual topology, thus packets
may be processed with a version of the network topology that's up to
session_gracetime too old.

* The MidoNet Agent will be unable to load new pieces of the network topology.
Packets that traverse devices that had never been loaded on a particular MidoNet
Agent will error out.

* The MidoNet Agent will not be able to perform or see updates to Address
Resolution Protocol (ARP) tables and Media Access Control (MAC) learning tables.

As time passes, a disconnected MidoNet Agent will become less and less useful.
The trade-offs presented above are key to choosing a sensible session_gracetime
value; the default is 30 seconds.

ZooKeeper connectivity is not an issue for the MidoNet API server. The API
requests are stateless and will simply fail when there is no ZooKeeper
connectivity.

== ZooKeeper configuration

You may use the ZooKeeper configuration section in +mn-conf(1)+ to adjust:

* the ZooKeeper session timeout value (in milliseconds). This value determines
when the system considers the connection between ZooKeeper and the MidoNet Agent
to be interrupted.

* the session grace timeout value (in milliseconds). This value determines the
period of time during which the Agent can reconnect to ZooKeeper without causing
node outage.

* the root path for MidoNet data.

[source]
----
zookeeper {
    zookeeper_hosts = <comma separated IPs>
    session_timeout = 30000
    root_key = /midonet/v1
    session_gracetime = 30000
}
----

=== Considerations for network partitions and ZooKeeper failure and maintenance

For the MidoNet Agents that run at compute hosts or L2GW hosts, setting the
session gracetime is primarily dictated by tradeoffs between maintaining
liveness of the datapath and maintaining consistency relative to the
authoritative network topology and security policy.

For L3GW hosts with BGP enabled, the considerations are more difficult. While
the MidoNet Agent at the L3GW continues to operate disconnected, it continues to
announce routes to its BGP peers. If the disconnection from ZooKeeper is due to
a network partition that also separates the L3GW from a majority of compute
hosts (rather than ZooKeeper failure/maintenance), then it is practically
black-holing the traffic destined to computes that are outside its partition.
Hence session gracetime presents a tradeoff between increasing L3GW tolerance to
ZooKeeper failure (by increasing gracetime) and reducing duration of traffic
blackholing (by reducing gracetime).

MidoNet currently does not have a good solution to this tradeoff. In the future
we intend to build a blackhole detection mechanism at the L3GW so that it can
shut down its BGP session during gracetime if it determines that it cannot
deliver most of the traffic it receives.

=== Scheduling ZooKeeper maintenance

When it's necessary to take all (or a majority) of ZooKeeper Quorum nodes down
for maintenance, the best practice is to increase the session_gracetime to a
value higher than the anticipated maintenance. This should be done for all
MidoNet Agents, both on computes and gateway hosts. After the maintenance event
the session_gracetime should be returned to the usual values, targeted at the
desired tradeoffs of consistency, ZooKeeper failure-tolerance and blackhole
duration (see discussion above).

== Cassandra configuration

You may use the Cassandra configuration section to adjust:

* the database replication factor

* the MidoNet cluster name

[source]
----
cassandra {
    servers = <comma separated IPs>
    replication_factor = 1
    cluster = midonet
}
----

== Datapath configuration

The agent uses a pool of reusable buffers to send requests to the datapath. You
may use the options in the +agent.datapath+ of mn-conf(1) to tune the pool's size
and its buffers. One pool is created for each output channel, the settings
defined here will apply to each of those pools.

If you notice decreased performance because packet sizes exceed the maximum
buffer size, you can increase the value for the buf_size_kb setting. This
setting controls the buffer size (in KB). Be aware that the buffer size puts a
limit on the packet size that the MidoNet Agent can send. In a network that
jumbo frames traverse, adjust the size so one buffer will accommodate a whole
frame, plus enough room for the flow's actions.

== BGP failover configuration

The default BGP fail-over time is 2-3 minutes. However, you can reduce this time
by changing some parameters on both ends of the session: in +mn-conf(1)+
(the MidoNet side) and the remote end BGP peer configuration. The example
below shows how to reduce the BGP fail-over time to one minute on the MidoNet
side:

[source]
----
agent {
    midolman {
        bgp_connect_retry=1
        bgp_holdtime=3
        bgp_keepalive=1
    }
}
----

The settings in mn-conf must match those on the remote end BGP peer configuration.
For more information about how to set them, see xref:bgp_failover[].

[[midolman_configuration_options]]
= MidoNet Agent (Midolman) configuration options

This section covers all configuration options for the MidoNet Agent.

We don't recommend making changes to the default values, except possibly the
+zookeeper.session_gracetime+ and +agent.datapath.send_buffer_pool_buf_size_kb+
setting values.

[WARNING]
Do not modify the root key, cluster name, or keyspace unless you know what you
are doing.

++++
<?dbhtml stop-chunking?>
++++

== MidoNet behavior after ZooKeeper cluster failure

Nodes running the MidoNet Agent, Midolman, depend on a live ZooKeeper session to
load pieces of a virtual network topology on-demand and watch for updates to
those virtual devices.

When ZooKeeper becomes inaccessible, a MidoNet Agent instance will continue
operating for as long as there's a chance to recover connectivity while keeping
the same ZooKeeper session. The amount of operating time is thus dictated by the
session timeout, which you can control by editing the zookeeper
session_gracetime setting in mn-conf(1).

Once the session expires, the MidoNet Agent will give up and shut itself down,
prompting upstart to re-launch it. If the ZooKeeper connection and session are
recovered within the session_gracetime, MidoNet Agent operation will resume
uneventfully. The MidoNet Agent will learn of all the updates that happened to
the virtual topology while it was disconnected and will update its internal
state and flow tables accordingly.

While the MidoNet Agent is running disconnected from ZooKeeper, waiting for the
session to come back, traffic will still be processed, but with reduced
functionality, as follows:

* The MidoNet Agent will not see updates to the virtual topology, thus packets
may be processed with a version of the network topology that's up to
session_gracetime too old.

* The MidoNet Agent will be unable to load new pieces of the network topology.
Packets that traverse devices that had never been loaded on a particular MidoNet
Agent will error out.

* The MidoNet Agent will not be able to perform or see updates to Address
Resolution Protocol (ARP) tables and Media Access Control (MAC) learning tables.

As time passes, a disconnected MidoNet Agent will become less and less useful.
The trade-offs presented above are key to choosing a sensible session_gracetime
value; the default is 30 seconds.

ZooKeeper connectivity is not an issue for the MidoNet API server. The API
requests are stateless and will simply fail when there is no ZooKeeper
connectivity.

== ZooKeeper configuration

You may use the ZooKeeper configuration section in +mn-conf(1)+ to adjust:

* the ZooKeeper session timeout value (in milliseconds). This value determines
when the system considers the connection between ZooKeeper and the MidoNet Agent
to be interrupted.

* the session grace timeout value (in milliseconds). This value determines the
period of time during which the Agent can reconnect to ZooKeeper without causing
node outage.

* the root path for MidoNet data.

[source]
----
zookeeper {
    zookeeper_hosts = <comma separated IPs>
    session_timeout = 30000
    root_key = /midonet/v1
    session_gracetime = 30000
}
----

== Cassandra configuration

You may use the Cassandra configuration section to adjust:

* the database replication factor

* the MidoNet cluster name

[source]
----
cassandra {
    servers = <comma separated IPs>
    replication_factor = 1
    cluster = midonet
}
----

== Datapath configuration

The agent uses a pool of reusable buffers to send requests to the datapath. You
may use the options in the +agent.datapath+ of mn-conf(1) to tune the pool's size
and its buffers. One pool is created for each output channel, the settings
defined here will apply to each of those pools.

If you notice decreased performance because packet sizes exceed the maximum
buffer size, you can increase the value for the buf_size_kb setting. This
setting controls the buffer size (in KB). Be aware that the buffer size puts a
limit on the packet size that the MidoNet Agent can send. In a network that
jumbo frames traverse, adjust the size so one buffer will accommodate a whole
frame, plus enough room for the flow's actions.

== BGP failover configuration

The default BGP fail-over time is 2-3 minutes. However, you can reduce this time
by changing some parameters on both ends of the session: in +mn-conf(1)+
(the MidoNet side) and the remote end BGP peer configuration. The example
below shows how to reduce the BGP fail-over time to one minute on the MidoNet
side:

[source]
----
agent {
    midolman {
        bgp_connect_retry=1
        bgp_holdtime=3
        bgp_keepalive=1
    }
}
----

The settings in mn-conf must match those on the remote end BGP peer configuration.
For more information about how to set them, see xref:bgp_failover[].


Typo in index.asciidoc.

Typo in index.asciidoc.

:toc:
:toclevels: 4

== Rewrite Annotations

toc::[]

The Rewrite annotation support offers an alternative way to configure Rewrite. Compared to configuring
Rewrite using a +ConfigurationProvider+, the annotations allow to place the configuration very close
to the affected code, which some people prefer over a central configuration.

Please note that the Rewrite annotations are not as flexible as a +ConfigurationProvider+.
The main focus of the annotations is to simplify the most common usecases which usually occur
many times in an application. A good example for this are +Join+ rules which are used very often.

NOTE: Of course you can use a +ConfigurationProvider+ and the annotations side by side.

=== Configuration

The annotation support of Rewrite is enabled by default. So you usually don't have do add any
additional configuration to use annotations.

If you care about the performance of the annotation scanning process, you can tell Rewrite which
packages to scan for annotations. Restricting the packages may increase performance if you have
a large number of classes in your application.

To tell Rewrite to scan only a specific package including all subpackes, add the following entry
to your +web.xml+:

[source,xml]
.Restrict annotation scanning to a specific package
----
<context-param>
  <param-name>org.ocpsoft.rewrite.annotation.BASE_PACKAGES</param-name>
  <param-value>com.example.myapp</param-value>
</context-param>
----

If you want to disable the annotation scanning completely, set the package to scan to +none+ like this:

[source,xml]
.Disable annotation scanning
----
<context-param>
  <param-name>org.ocpsoft.rewrite.annotation.BASE_PACKAGES</param-name>
  <param-value>none</param-value>
</context-param>
----

By default Rewrite will only scan the contents of your +/WEB-INF/classes+ directory.
Sometimes it makes sense to also scan the JAR files located in
+/WEB-INF/lib+. This may be the case if your are developing a highly modular application
which is split into different JAR files.

You can tell Rewrite to also scan the JAR files in +/WEB-INF/lib+ by adding the
following configuration to your +web.xml+:

[source,xml]
.Tell Rewrite to scan JAR files for annotations
----
<context-param>
  <param-name>org.ocpsoft.rewrite.annotation.SCAN_LIB_DIRECTORY</param-name>
  <param-value>true</param-value>
</context-param>
----

=== Defining rules with annotations

One of the most common Rewrite rule types is the +Join+ which maps a _virtual_ path to a physical
server resource. If you are using the +ConfigurationProvider+ way of configuration, adding a join
usually looks like this:

[source,java]
.A basic join using the fluent Java API
----
.addRule(Join.path("/welcome").to("/faces/welcome.xhtml"))
----

If you want to configure this rule using the Rewrite annotations API, you can do it like this:

[source,java]
.A basic join using Rewrite annotations
----
@Named
@RequestScoped
@Join(path="/welcome", to="/faces/welcome.xhtml")
public class WelcomePage {
  // your code
}
----

As you can see in this example, using the Rewrite annotations is straight forward. Just add
a +@Join+ annotation to your class and set the +path+ and +to+ attributes just like you would
using the fluent Java API.

TIP: When using web frameworks like JSF, it is recommended to place the annotation on the class
which is mainly responsible for the corresponding page.

In some cases it is desired to add an additional +Condition+ to a rule. A good example for this
are additional security checks for an URL. To add such a constraint, just add the corresponding annotation to
your class like shown in the following example.

[source,java]
.Adding a security constraint to a Join
----
@Named
@RequestScoped
@RolesRequired("ADMIN")
@Join(path="/users", to="/faces/user-list.xhtml")
public class UserListPage {
  // your code
}
----

In this example the +Join+ rules is only applied if the user as the required JAAS role.

TIP: If Rewrite doesn't provide an existing annotation for your specific usecase, you can create your
own one very easily. Have a look at <<custom-annotations,Building custom annotations>> to learn how
to do this.

=== Handling parameters

Parameters are a very important concept in Rewrite. They allow you to specify a _dynamic_ part of your
URL used to identify the resource the user is trying to access.

When using the +ConfigurationProvider+ API, you declare parameters like this:

[source,java]
.A join with parameters
----
.addRule(Join.path("/user/{name}").to("/faces/user-details.xhtml"))
----

If you want to define such a rule using Rewrite annotations, add the parameter
to the path just like you would using the +ConfigurationProvider+:

[source,java]
.Using parameters with @Join annotations
----
@Named
@RequestScoped
@Join(path="/user/{name}", to="/faces/user-details.xhtml"")
public class UserDetailsPage {
  // your code
}
----

Rewrite will automatically turn the parameter into a query parameter with the same name. So
you can access the value simply by calling +HttpServletRequest.getParameter()+:

[source,java]
.Accessing parameters using the Servlet API
----
String username = request.getParameter("name");
----

Of cause it is not very nice to spread such low level Servlet API calls across your code.
Therefore Rewrite also supports _parameter bindings_ which allow you to automatically
inject the parameter values into managed bean properties.

To inject the parameters into a property of you bean, just add a +@Parameter+ annotation
to the corresponding field like this:

[source,java]
.Using @Parameter to inject parameter values
----
@Named
@RequestScoped
@Join(path="/user/{name}", to="/faces/user-details.xhtml"")
public class UserListPage {

  @Parameter("name")
  private String username;

}
----

TIP: If you don't specify the name of the parameter in the annotation, Rewrite will instead
use the name of the field. So you don't have to specify the name if the name of the field
matches the name of the parameter.

[[parameter-custom-regex-pattern]]
==== Custom matching patterns

By default Rewrite parameters will match any character except for the path delimiter +/+.
Internally Rewrite uses the regular expression +[^/]++ for matching the value of the parameter.
In some situations it can be useful to customize this pattern. Especially if the standard
pattern matches too greedy or if you want to match more than a single path segment.

If you want to customize the regular expression used for the matching, just add a +@Matches+
annotation to the corresponding field. The following class contains a parameter that will
match only lowercase letters and digits.

[source,java]
.Using @Parameter to inject parameter values
----
@Named
@RequestScoped
@Join(path="/user/{name}", to="/faces/user-details.xhtml"")
public class UserListPage {

  @Parameter
  @Matches("[a-z0-9]+")
  private String name;

}
----

==== Custom validation

Many parameter validation requirements can be implemented using regular expressions like shown
in the <<parameter-custom-regex-pattern,previous section>>. If your validation rules are more
complex, you can use Rewrite's support for custom validators.

A validator must implement the interface +Validator+. The only method in this interface is
called +isValid()+ and must return +true+ if the parameter is valid and +false+ otherwise.
The following example shows an validator which validates that the length of a parameter value
is even.

[source,java]
.Example for a custom validator
----
public class EvenLengthValidator implements Validator<String>
{

   @Override
   public boolean isValid(Rewrite event, EvaluationContext context, String value)
   {
      return value.trim().length() % 2 == 0;
   }

}
----

To use such a custom validator, add a +@Validate+ annotation to your field and refer to the type
of the validator you wish to use:

[source,java]
.Using @ValidateWith for custom vaidation
----
@Named
@RequestScoped
@Join(path="/some-path/{value}", to="/faces/some-page.xhtml"")
public class SomePage {

  @Parameter
  @Validate(with = EvenLengthValidator.class)
  private String value;

}
----

TIP: If you are using the JSF integration module, you can also refer to standard JSF validators without
the need to create a Rewrite-specific one. Refer to the JSF integration module documentation
for details.

=== Invoking methods

TODO

[[custom-annotations]]

=== Building custom annotations

TODO

:toc:
:toclevels: 4

== Rewrite Annotations

toc::[]

The Rewrite annotation support offers an alternative way to configure Rewrite. Compared to configuring
Rewrite using a +ConfigurationProvider+, the annotations allow to place the configuration very close
to the affected code, which some people prefer over a central configuration.

Please note that the Rewrite annotations are not as flexible as a +ConfigurationProvider+.
The main focus of the annotations is to simplify the most common usecases which usually occur
many times in an application. A good example for this are +Join+ rules which are used very often.

NOTE: Of cause you can use a +ConfigurationProvider+ and the annotations side by side.

=== Configuration

The annotation support of Rewrite is enabled by default. So you usually don't have do add any
additional configuration to use annotations.

If you care about the performance of the annotation scanning process, you can tell Rewrite which
packages to scan for annotations. Restricting the packages may increase performance if you have
a large number of classes in your application.

To tell Rewrite to scan only a specific package including all subpackes, add the following entry
to your +web.xml+:

[source,xml]
.Restrict annotation scanning to a specific package
----
<context-param>
  <param-name>org.ocpsoft.rewrite.annotation.BASE_PACKAGES</param-name>
  <param-value>com.example.myapp</param-value>
</context-param>
----

If you want to disable the annotation scanning completely, set the package to scan to +none+ like this:

[source,xml]
.Disable annotation scanning
----
<context-param>
  <param-name>org.ocpsoft.rewrite.annotation.BASE_PACKAGES</param-name>
  <param-value>none</param-value>
</context-param>
----

By default Rewrite will only scan the contents of your +/WEB-INF/classes+ directory.
Sometimes it makes sense to also scan the JAR files located in
+/WEB-INF/lib+. This may be the case if your are developing a highly modular application
which is split into different JAR files.

You can tell Rewrite to also scan the JAR files in +/WEB-INF/lib+ by adding the
following configuration to your +web.xml+:

[source,xml]
.Tell Rewrite to scan JAR files for annotations
----
<context-param>
  <param-name>org.ocpsoft.rewrite.annotation.SCAN_LIB_DIRECTORY</param-name>
  <param-value>true</param-value>
</context-param>
----

=== Defining rules with annotations

One of the most common Rewrite rule types is the +Join+ which maps a _virtual_ path to a physical
server resource. If you are using the +ConfigurationProvider+ way of configuration, adding a join
usually looks like this:

[source,java]
.A basic join using the fluent Java API
----
.addRule(Join.path("/welcome").to("/faces/welcome.xhtml"))
----

If you want to configure this rule using the Rewrite annotations API, you can do it like this:

[source,java]
.A basic join using Rewrite annotations
----
@Named
@RequestScoped
@Join(path="/welcome", to="/faces/welcome.xhtml")
public class WelcomePage {
  // your code
}
----

As you can see in this example, using the Rewrite annotations is straight forward. Just add
a +@Join+ annotation to your class and set the +path+ and +to+ attributes just like you would
using the fluent Java API.

TIP: When using web frameworks like JSF, it is recommended to place the annotation on the class
which is mainly responsible for the corresponding page.

In some cases it is desired to add an additional +Condition+ to a rule. A good example for this
are additional security checks for an URL. To add such a constraint, just add the corresponding annotation to
your class like shown in the following example.

[source,java]
.Adding a security constraint to a Join
----
@Named
@RequestScoped
@RolesRequired("ADMIN")
@Join(path="/users", to="/faces/user-list.xhtml")
public class UserListPage {
  // your code
}
----

In this example the +Join+ rules is only applied if the user as the required JAAS role.

TIP: If Rewrite doesn't provide an existing annotation for your specific usecase, you can create your
own one very easily. Have a look at <<custom-annotations,Building custom annotations>> to learn how
to do this.

=== Handling parameters

Parameters are a very important concept in Rewrite. They allow you to specify a _dynamic_ part of your
URL used to identify the resource the user is trying to access.

When using the +ConfigurationProvider+ API, you declare parameters like this:

[source,java]
.A join with parameters
----
.addRule(Join.path("/user/{name}").to("/faces/user-details.xhtml"))
----

If you want to define such a rule using Rewrite annotations, add the parameter
to the path just like you would using the +ConfigurationProvider+:

[source,java]
.Using parameters with @Join annotations
----
@Named
@RequestScoped
@Join(path="/user/{name}", to="/faces/user-details.xhtml"")
public class UserDetailsPage {
  // your code
}
----

Rewrite will automatically turn the parameter into a query parameter with the same name. So
you can access the value simply by calling +HttpServletRequest.getParameter()+:

[source,java]
.Accessing parameters using the Servlet API
----
String username = request.getParameter("name");
----

Of cause it is not very nice to spread such low level Servlet API calls across your code.
Therefore Rewrite also supports _parameter bindings_ which allow you to automatically
inject the parameter values into managed bean properties.

To inject the parameters into a property of you bean, just add a +@Parameter+ annotation
to the corresponding field like this:

[source,java]
.Using @Parameter to inject parameter values
----
@Named
@RequestScoped
@Join(path="/user/{name}", to="/faces/user-details.xhtml"")
public class UserListPage {

  @Parameter("name")
  private String username;

}
----

TIP: If you don't specify the name of the parameter in the annotation, Rewrite will instead
use the name of the field. So you don't have to specify the name if the name of the field
matches the name of the parameter.

[[parameter-custom-regex-pattern]]
==== Custom matching patterns

By default Rewrite parameters will match any character except for the path delimiter +/+.
Internally Rewrite uses the regular expression +[^/]++ for matching the value of the parameter.
In some situations it can be useful to customize this pattern. Especially if the standard
pattern matches too greedy or if you want to match more than a single path segment.

If you want to customize the regular expression used for the matching, just add a +@Matches+
annotation to the corresponding field. The following class contains a parameter that will
match only lowercase letters and digits.

[source,java]
.Using @Parameter to inject parameter values
----
@Named
@RequestScoped
@Join(path="/user/{name}", to="/faces/user-details.xhtml"")
public class UserListPage {

  @Parameter
  @Matches("[a-z0-9]+")
  private String name;

}
----

==== Custom validation

Many parameter validation requirements can be implemented using regular expressions like shown
in the <<parameter-custom-regex-pattern,previous section>>. If your validation rules are more
complex, you can use Rewrite's support for custom validators.

A validator must implement the interface +Validator+. The only method in this interface is
called +isValid()+ and must return +true+ if the parameter is valid and +false+ otherwise.
The following example shows an validator which validates that the length of a parameter value
is even.

[source,java]
.Example for a custom validator
----
public class EvenLengthValidator implements Validator<String>
{

   @Override
   public boolean isValid(Rewrite event, EvaluationContext context, String value)
   {
      return value.trim().length() % 2 == 0;
   }

}
----

To use such a custom validator, add a +@Validate+ annotation to your field and refer to the type
of the validator you wish to use:

[source,java]
.Using @ValidateWith for custom vaidation
----
@Named
@RequestScoped
@Join(path="/some-path/{value}", to="/faces/some-page.xhtml"")
public class SomePage {

  @Parameter
  @Validate(with = EvenLengthValidator.class)
  private String value;

}
----

TIP: If you are using the JSF integration module, you can also refer to standard JSF validators without
the need to create a Rewrite-specific one. Refer to the JSF integration module documentation
for details.

=== Invoking methods

TODO

[[custom-annotations]]

=== Building custom annotations

TODO


Enforce one sentence per line

Enforce one sentence per line

// Copyright 2017 the original author or authors.
//
// 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.

[[java_gradle_plugin]]
= Gradle Plugin Development Plugin

The Java Gradle Plugin development plugin can be used to assist in the development of Gradle plugins.
It automatically applies the <<java_library_plugin.adoc#java_library_plugin,Java Library (`java-library`)>> plugin, adds the `gradleApi()` dependency to the `api` configuration and performs validation of plugin metadata during `jar` task execution.

The plugin also integrates with <<test_kit.adoc#test_kit,TestKit>>, a library that aids in writing and executing functional tests for plugin code.
It automatically adds the `gradleTestKit()` dependency to the `testImplementation` configuration and generates a plugin classpath manifest file consumed by a `GradleRunner` instance if found.
Please refer to <<test_kit.adoc#sub:test-kit-automatic-classpath-injection,Automatic classpath injection with the Plugin Development Plugin>> for more on its usage, configuration options and samples.

[[sec:gradle_plugin_dev_usage]]
== Usage

To use the Java Gradle Plugin Development plugin, include the following in your build script:

.Using the Java Gradle Plugin Development plugin
====
include::sample[dir="snippets/java/javaGradlePlugin/groovy",files="build.gradle[tags=use-java-gradle-plugin-plugin]"]
include::sample[dir="snippets/java/javaGradlePlugin/kotlin",files="build.gradle.kts[tags=use-java-gradle-plugin-plugin]"]
====

Applying the plugin automatically applies the <<java_library_plugin.adoc#java_library_plugin,Java Library(`java-library`)>> plugin and adds the `gradleApi()` dependency to the `api` configuration.
It also adds some validations to the build.

The following validations are performed:

* There is a plugin descriptor defined for the plugin.
* The plugin descriptor contains an `implementation-class` property.
* The `implementation-class` property references a valid class file in the jar.
* Each property getter or the corresponding field must be annotated with a property annotation like `@InputFile` and `@OutputDirectory`.
Properties that don't participate in up-to-date checks should be annotated with `@Internal`.

Any failed validations will result in a warning message.

For each plugin you are developing, add an entry to the `gradlePlugin {}` script block:

.Using the gradlePlugin {} block.
====
include::sample[dir="snippets/java/javaGradlePlugin/groovy",files="build.gradle[tags=gradle-plugin-block]"]
include::sample[dir="snippets/java/javaGradlePlugin/kotlin",files="build.gradle.kts[tags=gradle-plugin-block]"]
====

The `gradlePlugin {}` block defines the plugins being built by the project including the `id` and `implementationClass` of the plugin.
From this data about the plugins being developed, Gradle can automatically:

* Generate the plugin descriptor in the `jar` file's `META-INF` directory.
* Configure the <<plugins.adoc#sec:plugin_markers,Plugin Marker Artifact>> publications (Maven or Ivy) for each plugin.
* Publish each plugin to the Gradle Plugin Portal (see <<publishing_gradle_plugins.adoc#publishing_portal,Publishing Plugins to Gradle Plugin Portal>> for details), but only if the link:https://plugins.gradle.org/docs/publish-plugin[Plugin Publishing Plugin] has also been applied.

[[sec:gradle_plugin_dev_interactions]]
== Interactions

Some of the plugin's behaviour depends on other, related plugins also being applied in your build, namely the <<publishing_maven.adoc#publishing_maven,Maven Publish (`maven-publish`)>> and <<publishing_ivy.adoc#publishing_ivy,Ivy Publish (`ivy-publish`)>> plugins.

Other plugins auto apply the Java Gradle Plugin, like the link:https://plugins.gradle.org/plugin/com.gradle.plugin-publish[Plugin Publishing Plugin].

=== Maven Publish Plugin

When the Java Gradle Plugin (`java-gradle-plugin`) detects that the Maven Publish Plugin (`maven-publish`) is also applied by the build, it will automatically configure the following link:{groovyDslPath}/org.gradle.api.publish.maven.MavenPublication.html[MavenPublications]:

* a single "main" publication, named `pluginMaven`, based on the <<java_plugin.adoc#sec:java_plugin_publishing,main Java component>>
* multiple <<plugins.adoc#sec:plugin_markers,"marker" publications>> (one for each plugin defined in the `gradlePlugin {}` block), named `<pluginName>PluginMarkerMaven` (for example in the above example it would be `simplePluginPluginMarkerMaven`)

This automatic configuration happens in a link:{groovyDslPath}/org.gradle.api.Project.html#org.gradle.api.Project:afterEvaluate(org.gradle.api.Action)[Project.afterEvaluate()] block (so at the end of the <<build_lifecycle.adoc#sec:build_phases,build configuration phase>>), and only if these publications haven't already been defined, so it's possible to create and customise them during the earlier stages of build configuration.

=== Ivy Publish Plugin

When the Java Gradle Plugin(`java-gradle-plugin`) detects that the Ivy Publish Plugin (`ivy-publish`) is also applied by the build, it will automatically configure the following link:{groovyDslPath}/org.gradle.api.publish.ivy.IvyPublication.html[IvyPublications]:

* a single "main" publication, named `pluginIvy`, based on the <<java_plugin.adoc#sec:java_plugin_publishing,main Java component>>
* multiple <<plugins.adoc#sec:plugin_markers,"marker" publications>> (one for each plugin defined in the `gradlePlugin {}` block), named `<pluginName>PluginMarkerIvy` (for example in the above example it would be `simplePluginPluginMarkerIvy`)

This automatic configuration happens in a link:{groovyDslPath}/org.gradle.api.Project.html#org.gradle.api.Project:afterEvaluate(org.gradle.api.Action)[Project.afterEvaluate()] block (so at the end of the <<build_lifecycle.adoc#sec:build_phases,build configuration phase>>), and only if these publications haven't already been defined, so it's possible to create and customise them during the earlier stages of build configuration.

=== Plugin Publish Plugin

Starting from link:https://plugins.gradle.org/plugin/com.gradle.plugin-publish/1.0.0[version 1.0.0, the Plugin Publish Plugin] always auto-applies the Java Gradle Plugin (`java-gradle-plugin`) and the Maven Publish Plugin (`maven-publish`).