このマニュアルは作成中のものであり、現在は不完全です。
改善にご協力いただける場合は、READMEをご覧ください。

1 はじめに

Ratpackは、高速で効率的、進化可能で十分にテストされたHTTPアプリケーションを容易にするJavaライブラリのセットです。高性能で効率的なNettyイベント駆動型ネットワークエンジン上に構築されています。

Ratpackは純粋にランタイムです。インストール可能なパッケージや、結合されたビルドツール（例：Rails、Play、Grails）はありません。Ratpackアプリケーションを構築するには、任意のJVMビルドツールを使用できます。Ratpackプロジェクトは、プラグインを介してGradleを特にサポートしていますが、他のツールも使用できます。

RatpackはライブラリJARのセットとして公開されています。ratpack-coreライブラリは、厳密に必要な唯一のライブラリです。ratpack-groovy、ratpack-guice、ratpack-jackson、ratpack-testなどはオプションです。

1.1 目標

Ratpackの目標は以下のとおりです。

高速でスケーラブル、効率的であること
アプリケーションが複雑化しても妥協せずに進化できるようにすること
ノンブロッキングプログラミングの利点を活用し、コストを削減すること
他のツールやライブラリを統合する際に柔軟で先入観を持たないこと
アプリケーションを簡単かつ徹底的にテストできるようにすること

Ratpackの目標はではありません。

完全に統合された、「フルスタック」ソリューションであること
必要なすべての機能をきちんとまとめた箱で提供すること
「ビジネスロジック」のアーキテクチャまたはフレームワークを提供すること

2.1 このドキュメントについて

Ratpackのドキュメントは、このマニュアルとJavadoc APIリファレンスに分散しています。マニュアルでは、トピックと概念をハイレベルで紹介し、詳細なAPI情報についてはJavadocにリンクしています。情報の大部分はJavadocに含まれています。Ratpackのコアコンセプトを理解したら、マニュアルの有用性は低下し、Javadocの有用性が高まることが期待されます。

1.2.1 コードサンプル

ドキュメント内のすべてのコードサンプルはテストされており、ほとんどがコピー＆ペーストして実行できる完全なプログラムです（適切なクラスパスなどが与えられている場合）。

ほとんどのサンプルは、テスト中の小さな埋め込みRatpackアプリケーションとして提供されます。以下は、Ratpackコードサンプルの「Hello World」です。

import ratpack.test.embed.EmbeddedApp;
import static org.junit.jupiter.api.Assertions.assertEquals;
 
public class Example {
  public static void main(String... args) throws Exception {
    EmbeddedApp.fromHandler(ctx -> 
      ctx.render("Hello World!")
    ).test(httpClient -> 
      assertEquals("Hello World!", httpClient.getText())
    );
  }
}

importステートメントは、明確にするためにデフォルトで折りたたまれています。クリックすると表示/非表示になります。

この例は、完全なRatpackアプリケーションです。ただし、EmbeddedAppは、通常のアプリケーションで使用されるエントリポイントではありません（通常の開始ポイントの詳細については、起動の章を参照してください）。EmbeddedAppはテスト指向です。これにより、大規模なアプリケーション中に非常に小さな（または本格的な）アプリを簡単に開始/停止でき、アプリに対してHTTPリクエストを行う便利な方法を提供します。APIに焦点を当てるために、ブートストラップの量を最小限に抑えるために例で使用されています。

この例では、すべてのHTTPリクエストに対してプレーンテキスト文字列「Hello World」で応答するデフォルト構成で、エフェメラルポートでRatpackサーバーを起動しています。ここで使用されているtest()メソッドは、テスト中のサーバーにリクエストを行うように構成されたTestHttpClientを指定された関数に提供します。この例や他のすべての同様の例は、RatpackサーバーにHTTPリクエストを行っています。EmbeddedAppとTestHttpClientは、Ratpackのテストサポートの一部として提供されています。

多くの例で使用されているもう1つの重要なテストユーティリティは、ExecHarnessです。

import com.google.common.io.Files;
import ratpack.test.exec.ExecHarness;
import ratpack.exec.Blocking;

import java.io.File;
import java.nio.charset.StandardCharsets;

import static org.junit.jupiter.api.Assertions.assertEquals;

public class Example {
  public static void main(String... args) throws Exception {
    File tmpFile = File.createTempFile("ratpack", "test");
    Files.asCharSink(tmpFile, StandardCharsets.UTF_8).write("Hello World!");
    tmpFile.deleteOnExit();

    String content = ExecHarness.yieldSingle(e ->
        Blocking.get(() -> Files.asCharSource(tmpFile, StandardCharsets.UTF_8).read())
    ).getValueOrThrow();

    assertEquals("Hello World!", content);
  }
}

EmbeddedAppがRatpackアプリケーション全体の作成をサポートしている場合、ExecHarnessはRatpackの実行モデルのインフラストラクチャのみを提供します。これは通常、PromiseのようなRatpackの構成要素を使用する非同期コードをユニットテストするために使用されます（実行モデルの詳細については、「非同期＆ノンブロッキング」の章を参照してください）。ExecHarnessもRatpackのテストサポートの一部として提供されています。

1.1.2.1 Java 8 スタイル

RatpackはJava 8上に構築されており、Java 8が必要です。コードサンプルでは、ラムダ式やメソッド参照などのJava 8の構成要素を多用しています。Javaの経験はあるが、Java 8の新しい構成要素に慣れていない場合は、例が「エキゾチック」に感じるかもしれません。