第47章 API コンポーネント Maven プラグインの設定

概要

本章では、API コンポーネント Maven プラグインで利用可能なすべての設定オプションのリファレンスを提供します。

47.1. プラグイン設定の概要

概要

API コンポーネント Maven プラグイン camel-api-component-maven-plugin の主な目的は、エンドポイント URI と API メソッド呼び出し間のマッピングを実装する API マッピングクラスを生成することです。API コンポーネント Maven プラグインの設定を編集することにより、API マッピングのさまざまな側面をカスタマイズできます。

生成されたコードの場所

API コンポーネント Maven プラグインによって生成された API マッピングクラスは、デフォルトで以下の場所に配置されます。

ProjectName-component/target/generated-sources/camel-component

前提条件

API コンポーネント Maven プラグインの主な入力は、Java API クラスおよび Javadoc メタデータです。これらは、通常の Maven 依存関係として宣言することで、プラグインで利用できます (Javadoc の Maven 依存関係を provided スコープで宣言する必要があります)。

プラグインの設定

API コンポーネント Maven プラグインの設定方法として、API コンポーネントの archetype を使用して開始点とするコードを生成することが推奨されます。これにより、プロジェクト用にカスタマイズできるデフォルトのプラグイン設定が ProjectName-component/pom.xml ファイルに生成されます。プラグインのセットアップの主な内容は以下のとおりです。

  1. 必要な Java API と Javadoc メタデータに対して、Maven の依存関係を宣言する必要があります。
  2. プラグインの基本設定は pluginManagement スコープで宣言されます (使用するプラグインのバージョンも定義します) 。
  3. プラグインインスタンス自体が宣言され、設定されます。
  4. build-helper-maven プラグインは、target/generated-sources/camel-component ディレクトリーから生成されたソースを取得して、Maven ビルドに含めるように設定されています。

基本設定のサンプル

以下の POM ファイルの抜粋は、API コンポーネント Maven プラグインの基本設定です。API コンポーネント archetype を使用してコードが生成された際に、Maven pluginManagement スコープで定義されます。

<?xml version="1.0" encoding="UTF-8"?>
<project ...>
  ...
  <build>
    ...
    <pluginManagement>
      <plugins>
        <plugin>
          <groupId>org.apache.camel</groupId>
          <artifactId>camel-api-component-maven-plugin</artifactId>
          <version>2.23.2.fuse-7_10_0-00018-redhat-00001</version>
          <configuration>
            <scheme>${schemeName}</scheme>
            <componentName>${componentName}</componentName>
            <componentPackage>${componentPackage}</componentPackage>
            <outPackage>${outPackage}</outPackage>
          </configuration>
        </plugin>
      </plugins>
    </pluginManagement>
    ...
  </build>
  ...
</project

pluginManagement スコープで指定した設定は、プラグインのデフォルト設定を提供します。実際にはプラグインのインスタンスを作成するわけではありませんが、デフォルト設定は API コンポーネントプラグインインスタンスによって使用されます。

基本設定

前述の基本設定では、(version 要素で) プラグインバージョンを指定する他に、以下の設定プロパティーを指定します。

scheme
この API コンポーネントの URI スキーム。
componentName
この API コンポーネントの名前 (生成されるクラス名の接頭辞としても使用されます)。
componentPackage
API コンポーネント Maven archetype によって生成されたクラスが含まれる Java パッケージを指定します。このパッケージは、デフォルトの maven-bundle-plugin 設定でもエクスポートされます。したがって、クラスを一般に公開する場合は、この Java パッケージに配置してください。
outPackage
生成された API マッピングクラスが配置される Java パッケージを指定します (API コンポーネント Maven プラグインによって生成された場合) 。デフォルトでは、これには componentName プロパティーの値があり、.internal 接尾辞が追加されています。このパッケージは、デフォルトの maven-bundle-plugin 設定では private として宣言されています。したがって、クラスを private にする場合は、この Java パッケージに配置してください。

インスタンスの設定例

以下の POM ファイルの抜粋は、API コンポーネント Maven プラグインのサンプルインスタンスを示しています。このインスタンスは、Maven ビルド中に API マッピングを生成するよう設定されています。

<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/maven-v4_0_0.xsd">

  ...
  <build>
    <defaultGoal>install</defaultGoal>

    <plugins>
      ...
      <!-- generate Component source and test source -->
      <plugin>
        <groupId>org.apache.camel</groupId>
        <artifactId>camel-api-component-maven-plugin</artifactId>
        <executions>
          <execution>
            <id>generate-test-component-classes</id>
            <goals>
              <goal>fromApis</goal>
            </goals>
            <configuration>
              <apis>
                <api>
                  <apiName>hello-file</apiName>
                  <proxyClass>org.jboss.fuse.example.api.ExampleFileHello</proxyClass>
                  <fromSignatureFile>signatures/file-sig-api.txt</fromSignatureFile>
                </api>
                <api>
                  <apiName>hello-javadoc</apiName>
                  <proxyClass>org.jboss.fuse.example.api.ExampleJavadocHello</proxyClass>
                  <fromJavadoc/>
                </api>
              </apis>
            </configuration>
          </execution>
        </executions>
      </plugin>
      ...
    </plugins>
    ...
  </build>
  ...
</project>

基本的なマッピングの設定

プラグインは、Java API のクラスを設定するための単一の apis 子要素が含まれる configuration 要素によって設定されます。各 API クラスは以下のように api 要素によって設定されます。

apiName

API name は、API クラスの短縮名で、エンドポイント URI の endpoint-prefix として使用されます。

注記

API が単一の Java クラスのみで設定される場合は、apiName 要素を空のままにすることができます。これにより、endpoint-prefix は冗長になります。その後、「単一 API クラスの URI 形式」 に示す形式を使用して、エンドポイント URI を指定できます。

proxyClass
この要素は、API クラスの完全修飾名を指定します。
fromJavadoc
API クラスに Javadoc メタデータが付随する場合、それを示すために fromJavadoc 要素を含める必要があります。provided 依存関係として、Javadoc 自体も Maven ファイルで指定する必要があります。
fromSignatureFile

API クラスに署名ファイルのメタデータが付随する場合、これを示すために fromSignatureFile 要素を含める必要があります。この要素の内容で署名ファイルの場所を指定します。

注記

署名ファイルは、実行時ではなくビルド時にのみ必要であるため、Maven によってビルドされた最終パッケージには含まれません

API マッピングのカスタマイズ

プラグインを設定することで、API マッピングの以下の部分をカスタマイズすることができます。

  • メソッドのエイリアス: aliases 設定要素を使用して API メソッドの名前 (エイリアス) を定義できます。詳細は、「メソッドのエイリアス」 を参照してください。
  • Null 可能なオプション - nullableOptions 設定要素を使用して、デフォルトが null のメソッド引数を宣言することができます。詳細は、「Null 可能なオプション」 を参照してください。
  • 引数名の置換: API マッピングの実装方法により、特定の API クラスのすべてのメソッドの引数は 同じ 名前空間に属します。同じ名前の 2 つの引数が異なる型であると宣言されている場合は競合になります。このような名前の競合を回避するには、substitutions 設定要素を使用してメソッド引数の名前を変更することができます (URI 内で表示されます) 。詳細は、「引数名の置換」 を参照してください。
  • 引数の除外: Java の引数を URI オプションにマッピングする際、マッピングから特定の引数を除外することがあります。excludeConfigNames 要素または excludeConfigTypes 要素のどちらかを指定し、不要な引数をフィルターリングすることができます。詳細は、「除外された引数」 を参照してください。
  • 追加オプション : Java API の一部ではない追加のオプションを定義することがあります。これは extraOptions 設定要素を使って行うことができます。

Javadoc のメタデータ設定

Javadoc のメタデータをフィルターして、特定のコンテンツを無視または明示的に含めることができます。設定方法の詳細については、「Javadoc オプション」 を参照してください。

署名ファイルのメタデータ設定

Javadoc が利用できない場合、必要なマッピングメタデータを提供するために署名ファイルを用いることができます。fromSignatureFile は、対応する署名ファイルの場所を指定するために使用されます。特別なオプションはありません。