Red Hat build of Apache Camel for Quarkus を使用したアプリケーションの開発

新規プロジェクトで適切な依存関係バージョンを取得する最も簡単でわかりやすい方法は、Quarkus ツールのいずれかを使用することです。

これらのツールを使用すると、エクステンションを選択し、新しい Maven プロジェクトのスキャフォールディングを行うことができます。

生成される pom.xml は以下のようになります。

<project>
  ...
  <properties>
    <quarkus.platform.artifact-id>quarkus-bom</quarkus.platform.artifact-id>
    <quarkus.platform.group-id>com.redhat.quarkus.platform</quarkus.platform.group-id>
    <quarkus.platform.version>
        <!-- The latest 3.2.x version from https://maven.repository.redhat.com/ga/com/redhat/quarkus/platform/quarkus-bom -->
    </quarkus.platform.version>
    ...
  </properties>
  <dependencyManagement>
    <dependencies>
      <!-- The BOMs managing the dependency versions -->
      <dependency>
        <groupId>${quarkus.platform.group-id}</groupId>
        <artifactId>quarkus-bom</artifactId>
        <version>${quarkus.platform.version}</version>
        <type>pom</type>
        <scope>import</scope>
      </dependency>
      <dependency>
        <groupId>${quarkus.platform.group-id}</groupId>
        <artifactId>quarkus-camel-bom</artifactId>
        <version>${quarkus.platform.version}</version>
        <type>pom</type>
        <scope>import</scope>
      </dependency>
    </dependencies>
  </dependencyManagement>

  <dependencies>
    <!-- The extensions you chose in the project generator tool -->
    <dependency>
      <groupId>org.apache.camel.quarkus</groupId>
      <artifactId>camel-quarkus-sql</artifactId>
      <!-- No explicit version required here and below -->
    </dependency>
    ...
  </dependencies>
  ...
</project>

どの BOM が pom.xml ファイルに保存されるかは、ジェネレーターツールで選択したエクステンションによって異なります。ジェネレーターツールは、一貫した最小限のセットを選択します。

pom.xml ファイルの BOM で管理されていないエクステンションを後で追加する場合も、適切な BOM を手動で検索する必要はありません。

quarkus-maven-plugin を使用してエクステンションを選択すると、ツールが必要に応じて適切な BOM を追加します。また、quarkus-maven-plugin を使用して、BOM バージョンをアップグレードすることもできます。

com.redhat.quarkus.platform の BOM は相互に調整されます。つまり、アーティファクトが複数の BOM で管理されている場合は、常に同じバージョンで管理されます。これには、アプリケーション開発者が、独立した各種プロジェクトからの個々のアーティファクトの互換性に注意する必要がないという利点があります。

camel-quarkus-bom を他の BOM と組み合わせる場合は、インポートの順序が優先順位を定義するため、これらをインポートする順番を慎重に検討してください。

つまり、my-foo-bom を camel-quarkus-bom より前にインポートした場合、my-foo-bom で定義されたバージョンが優先されます。この優先順位が希望するものかどうかは、my-foo-bom と camel-quarkus-bom の間に重複があるかどうか、および優先順位の高いバージョンが camel-quarkus-bom で管理される残りのアーティファクトと連携するかどうかによって決まります。

org.apache.camel.builder.RouteBuilder を拡張し、そこで利用可能な Fluent Builder メソッドを使用することが、Camel ルートを定義する最も一般的な方法です。以下は、タイマーコンポーネントを使用したルートの簡単な例です。

import org.apache.camel.builder.RouteBuilder;

public class TimerRoute extends RouteBuilder {

    @Override
    public void configure() throws Exception {
        from("timer:foo?period=1000")
                .log("Hello World");
    }
}

import org.apache.camel.builder.RouteBuilder;
import static org.apache.camel.builder.endpoint.StaticEndpointBuilders.timer;

public class TimerRoute extends RouteBuilder {

    @Override
    public void configure() throws Exception {
        from(timer("foo").period(1000))
                .log("Hello World");
    }
}

プロパティーによる Camel の設定に加え、camel-quarkus-core では、規則を使用して Camel の動作を設定できます。たとえば、CDI コンテナーに単一の ExchangeFormatter インスタンスがある場合は、その Bean を LogComponent に自動的に接続します。

CamelContext にアクセスするには、CamelContext を Bean に注入します。

import jakarta.inject.Inject;
import jakarta.enterprise.context.ApplicationScoped;
import java.util.stream.Collectors;
import java.util.List;
import org.apache.camel.CamelContext;

@ApplicationScoped
public class MyBean {

    @Inject
    CamelContext context;

    public List<String> listRouteIds() {
        return context.getRoutes().stream().map(Route::getId).sorted().collect(Collectors.toList());
    }
}

プレーン Camel または SpringBoot 上の Camel から @org.apache.camel.EndpointInject と @org.apache.camel.Produce を使用することに慣れている場合は、これらを Quarkus でも引き続き使用できます。

次のユースケースは、org.apache.camel.quarkus:camel-quarkus-core によってサポートされています。

import jakarta.enterprise.context.ApplicationScoped;
import org.apache.camel.EndpointInject;
import org.apache.camel.FluentProducerTemplate;
import org.apache.camel.Produce;
import org.apache.camel.ProducerTemplate;

@ApplicationScoped
class MyBean {

    @EndpointInject("direct:myDirect1")
    ProducerTemplate producerTemplate;

    @EndpointInject("direct:myDirect2")
    FluentProducerTemplate fluentProducerTemplate;

    @EndpointInject("direct:myDirect3")
    DirectEndpoint directEndpoint;

    @Produce("direct:myDirect4")
    ProducerTemplate produceProducer;

    @Produce("direct:myDirect5")
    FluentProducerTemplate produceProducerFluent;

}

direct:myDirect* の代わりに、他の Camel プロデューサーエンドポイント URI を使用できます。

次のユースケースは org.apache.camel.quarkus:camel-quarkus-bean でサポートされています。

import jakarta.enterprise.context.ApplicationScoped;
import org.apache.camel.Produce;

@ApplicationScoped
class MyProduceBean {

    public interface ProduceInterface {
        String sayHello(String name);
    }

    @Produce("direct:myDirect6")
    ProduceInterface produceInterface;

    void doSomething() {
        produceInterface.sayHello("Kermit")
    }

}

ヘルス/liveness チェックは MicroProfile Health エクステンションでサポートされます。チェックは Camel Health API または Quarkus MicroProfile Health を使用して設定できます。

設定したチェックは、すべて標準の MicroProfile Health エンドポイント URL で利用できます。

Red Hat は、メトリクスを公開するための MicroProfile メトリクス を提供しています。

一部の基本的な Camel メトリクスは最初から提供されており、ルートに追加メトリクスを設定することで、このメトリクスを補完できます。

メトリックは、標準の Quarkus メトリックエンドポイントで利用できます。

デフォルトでは、すべての Charset がネイティブモードで利用できる訳ではありません。

Charset.defaultCharset(), US-ASCII, ISO-8859-1, UTF-8, UTF-16BE, UTF-16LE, UTF-16

アプリケーションでこのセットに含まれていないエンコーディングが必要な場合や、ネイティブモードで UnsupportedCharsetException が出力された場合は、以下のエントリーを application.properties に追加してください。

quarkus.native.add-all-charsets = true

Quarkus ドキュメントの quarkus.native.add-all-charsets も参照してください。

デフォルトでは、JVM のデフォルトロケールのビルドのみがネイティブイメージに含まれます。Quarkus では、application.properties を介してロケールを設定する方法を提供しているため、LANG および LC_* 環境変数に依存する必要はありません。

quarkus.native.user-country=US
quarkus.native.user-language=en

また、複数のロケールをネイティブイメージに組み込むことや、Mandel コマンドラインオプション -H:IncludeLocales=fr,en、H:+IncludeAllLocales、および -H:DefaultLocale=de を使用してデフォルトのロケールを選択することもサポートされます。これらは、Quarkus quarkus.native.additional-build-args プロパティーで設定できます。

ランタイム時に Class.getResource()、Class.getResourceAsStream()、ClassLoader.getResource()、ClassLoader.getResourceAsStream() などを介してアクセスされるリソースをネイティブ実行可能ファイルに組み込むには、明示的にリストする必要があります。

これは、以下のように application.properties ファイルの Quarkus quarkus.native.resources.includes および quarkus.native.resources.excludes プロパティーを使用して実行できます。

quarkus.native.resources.includes = docs/*,images/*
quarkus.native.resources.excludes = docs/ignored.adoc,images/ignored.png

上記の例では、docs/included.adoc および images/included.png という名前のリソースはネイティブ実行可能ファイルに組み込まれ、docs/ignored.adoc および images/ignored.png のリソースはネイティブ実行可能ファイルに組み込まれません。

resources.includes および resources.excludes は、どちらも Ant パススタイルの glob パターンのコンマ区切りリストです。

詳細は、Red Hat build of Apache Camel for Quarkus リファレンス を参照してください。

Camel onException 処理 をネイティブモードで使用する場合、ユーザーはリフレクションの例外クラスを登録する必要があります。

たとえば、onException 処理のある camel コンテキストは以下のようになります。

onException(MyException.class).handled(true);
from("direct:route-that-could-produce-my-exception").throw(MyException.class);

クラス mypackage.MyException をリフレクション用に登録する必要があります。詳細は、リフレクション用のクラスの登録 を参照してください。

デフォルトでは、動的リフレクションはネイティブモードでは使用できません。リフレクションアクセスが必要なクラスは、コンパイル時にリフレクション用に登録する必要があります。

多くの場合、Quarkus エクステンションはリフレクションを必要とするクラスを検出して自動的に登録できるため、アプリケーション開発者は注意する必要はありません。

ただし、状況によっては、Quarkus のエクステンションはクラスの一部を見逃す場合があるため、アプリケーション開発者が登録を行う必要があります。これには 2 つの方法があります。

quarkus.camel.native.reflection.serialization-enabled を介してシリアル化サポートが要求されると、CamelSerializationProcessor.BASE_SERIALIZATION_CLASSES に一覧表示されているクラスは、シリアル化のために自動的に登録されます。

@RegisterForReflection(serialization = true) を使用してさらに多くのクラスを登録できます。