45.2. フレームワークの使用方法

概要

API フレームワークを使用してコンポーネントを実装する手順には、Maven POM ファイルを編集して、自動化されたコード生成、Java コードの実装、およびビルドのカスタマイズが関係します。以下の図は、この開発プロセスの概要を示しています。

図45.1 API コンポーネントフレームワークの使用

API コンポーネント実装の一部を示す図

Java API

API コンポーネントの始点は常に Java API です。通常、Camel のコンテキストでは、リモートサーバーエンドポイントに接続する Java クライアント API を意味します。最初の質問は、Java API のソースが何であるかです。以下である可能性があります。

  • Java API を独自に実装します (ただし、これは通常多くの作業を伴い、一般的には推奨されません)。
  • サードパーティーの Java API を使用します。たとえば、Apache Camel Box コンポーネントはサードパーティーの Box Java SDK ライブラリーに基づいています。
  • 言語に依存しないインターフェイスから Java API を生成します。

Javadoc メタデータ

Javadoc (API コンポーネントフレームワークでコードを生成するのに必要な) 形式で Java API のメタデータを提供するオプションがあります。Maven リポジトリーからサードパーティーの Java API を使用する場合、通常は Javadoc がすでに Maven アーティファクトで提供されています。ただし、Javadoc が提供されて いない 場合でも、maven-javadoc-plugin Maven プラグインを使用すると簡単に生成できます。

注記

現在、Javadoc メタデータの処理には、一般的なネストには対応していないといった制限があります。たとえば、java.util.List<String> がサポートされていますが、java.util.List<java.util.List<String>> はサポートされていません。回避策として、ネストされた汎用タイプを署名ファイルで java.util.List<java.util.List> として指定します。

署名ファイルメタデータ

何らかの理由で Javadoc の形式で Java API メタデータを提供することが適切ではない場合がありますが、署名ファイル の形式でメタデータを提供するオプションがあります。署名ファイルは、メソッド署名のリストで設定されます (行ごとに 1 つのメソッド署名)。これらのファイルは手動で作成でき、ビルド時にのみ必要です。

署名ファイルについては、以下の点に注意してください。

  • 各プロキシークラス (Java API クラス) ごとに署名ファイルを 1 つ作成する必要があります。
  • メソッドの署名では例外は発生 しません。ランタイム時に発生するすべての例外は、RuntimeCamelException でラップされ、エンドポイントから返されます。
  • 引数のタイプを指定するクラス名は完全修飾クラス名である必要があります (java.lang.\* タイプを除く)。パッケージ名をインポートするメカニズムはありません。
  • 現在、署名パーサーには、一般的なネストがサポートされていないといった制限があります。たとえば、java.util.List<String> がサポートされていますが、java.util.List<java.util.List<String>> はサポートされていません。回避策として、ネストされた汎用タイプを java.util.List<java.util.List> として指定します。

以下は、署名ファイルの内容の簡単な例です。

public String sayHi();
public String greetMe(String name);
public String greetUs(String name1, String name2);

Maven archetype での開始コードの生成

API コンポーネントの開発を開始する最も簡単な方法は、camel-archetype-api-component Maven archetype を使用して初期 Maven プロジェクトを生成することです。archetype の実行方法は、「Maven archetype でのコードの生成」 を参照してください。

Maven archetype を実行すると、生成された ProjectName ディレクトリーの下に 2 つのサブプロジェクトが表示されます。

ProjectName-api
このプロジェクトには、API コンポーネントの基礎を設定する Java API が含まれます。このプロジェクトをビルドする際に、Maven バンドルで Java API をパッケージ化し、必要な Javadoc も生成します。Java API および Javadoc がサードパーティーによってすでに提供されている場合は、このサブプロジェクトは必要ありません。
ProjectName-component
このプロジェクトには、API コンポーネントのスケルトンコードが含まれます。

コンポーネントクラスの編集

ProjectName-component のスケルトンコードを編集して、独自のコンポーネント実装を開発することができます。以下の生成されたクラスはスケルトン実装の中核を成しています。

ComponentNameComponent
ComponentNameEndpoint
ComponentNameConsumer
ComponentNameProducer
ComponentNameConfiguration

POM ファイルのカスタマイズ

また、Maven POM ファイルを編集してビルドをカスタマイズし、camel-api-component-maven-plugin Maven プラグインを設定する必要もあります。

camel-api-component-maven-plugin の設定

POM ファイルの設定で最も重要なことは、camel-api-component-maven-plugin Maven プラグインの設定です。このプラグインは、API メソッドとエンドポイント URI 間のマッピングを生成し、プラグイン設定を編集してマッピングをカスタマイズできます。

たとえば、ProjectName-component/pom.xml ファイルでは、以下の camel-api-component-maven-plugin プラグイン設定は、ExampleJavadocHello という API クラスの最小限の設定を示しています。

<configuration>
  <apis>
    <api>
      <apiName>hello-javadoc</apiName>
      <proxyClass>org.jboss.fuse.example.api.ExampleJavadocHello</proxyClass>
      <fromJavadoc/>
    </api>
  </apis>
</configuration>

この例では、hello-javadoc API 名は ExampleJavadocHello クラスにマップされています。つまり、scheme://hello-javadoc/endpoint 形式の URI を使用して、このクラスからメソッドを呼び出すことができます。fromJavadoc 要素が存在する場合は、ExampleJavadocHello クラスが Javadoc からメタデータを取得することを示しています。

OSGi バンドルの設定

component サブプロジェクトのサンプル POM である ProjectName-component/pom.xml は、コンポーネントを OSGi バンドルとしてパッケージ化するように設定されています。コンポーネント POM には、maven-bundle-plugin の設定例が含まれています。Maven がコンポーネント用に適切に設定された OSGi バンドルを生成するには、maven-bundle-plugin プラグインの設定をカスタマイズする必要があります。

コンポーネントの構築

Maven でコンポーネントをビルドする場合 (例: mvn clean package を使用)、camel-api-component-maven-plugin プラグインは (Java API とエンドポイント URI 構文間のマッピングを定義する) API マッピングクラスを自動的に生成し、それらを target/classes プロジェクトのサブディレクトリーに配置します。大規模で複雑な Java API を扱う場合、この生成されたコードは実際にはコンポーネントのソースコードの大部分を設定します。

Maven ビルドが完了すると、コンパイルされたコードおよびリソースが OSGi バンドルとしてパッケージ化され、ローカル Maven リポジトリーに Maven アーティファクトとして保存されます。