第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
ファイルに生成されます。プラグインのセットアップの主な内容は以下のとおりです。
- 必要な Java API と Javadoc メタデータに対して、Maven の依存関係を宣言する必要があります。
-
プラグインの基本設定は
pluginManagement
スコープで宣言されます (使用するプラグインのバージョンも定義します) 。 - プラグインインスタンス自体が宣言され、設定されます。
-
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
は、対応する署名ファイルの場所を指定するために使用されます。特別なオプションはありません。