5.3. Web サービスのバンドルへのパッケージ化

5.3.1. 概要

このセクションでは、Apache CXF アプリケーションの既存の Maven プロジェクトを変更して、プロジェクトが Red Hat Fuse OSGi コンテナーでのデプロイメントに適した OSGi バンドルを生成する方法について説明します。Maven プロジェクトを変換するには、プロジェクトの POM ファイルとプロジェクトの Blueprint ファイル (META-INF/spring にある) を変更する必要があります。

5.3.2. バンドルを生成するための POM ファイルの変更

バンドルを生成するように Maven POM ファイルを設定するには、基本的に 2 つの変更を行う必要があります。1 つ目は、POM のパッケージ型を bundle に変更します。2 つ目は、Maven バンドルプラグインを POM に追加します。詳細は、「バンドルプロジェクトの生成」 を参照してください。

5.3.3. 必須のインポートパッケージ

アプリケーションで Apache CXF コンポーネントを使用するには、それらのパッケージをアプリケーションのバンドルにインポートする必要があります。Apache CXF の依存関係は複雑であるため、Maven バンドルプラグインや bnd ツールに依存して必要なインポートを自動的に決定することができません。それらを明示的に宣言する必要があります。

次のパッケージをバンドルにインポートする必要があります。

javax.jws
javax.wsdl
javax.xml.bind
javax.xml.bind.annotation
javax.xml.namespace
javax.xml.ws
org.apache.cxf.bus
org.apache.cxf.bus.spring
org.apache.cxf.bus.resource
org.apache.cxf.configuration.spring
org.apache.cxf.resource
org.apache.cxf.jaxws
org.springframework.beans.factory.config

5.3.4. Maven バンドルプラグインの手順例

例5.1「必須のインポートパッケージの設定」 は、必須パッケージをインポートするように POM で Maven バンドルプラグインを設定する方法を示しています。必須のインポートパッケージは、Import-Package 要素内にコンマ区切りリストとして存在します。リストの最後の要素にワイルドカード (*) があることに注意してください。ワイルドカードにより、現在のバンドルの Java ソースファイルがスキャンされ、インポートする必要のある追加のパッケージが検出されます。

例5.1 必須のインポートパッケージの設定

<project ... >
    ...
    <build>
        <plugins>
            <plugin>
                <groupId>org.apache.felix</groupId>
                <artifactId>maven-bundle-plugin</artifactId>
                <extensions>true</extensions>
                <configuration>
                    <instructions>
                        ...
                        <Import-Package>
                            javax.jws,
                            javax.wsdl,
                            javax.xml.bind,
                            javax.xml.bind.annotation,
                            javax.xml.namespace,
                            javax.xml.ws,
                            org.apache.cxf.bus,
                            org.apache.cxf.bus.spring,
                            org.apache.cxf.bus.resource,
                            org.apache.cxf.configuration.spring,
                            org.apache.cxf.resource,
                            org.apache.cxf.jaxws,
                            org.springframework.beans.factory.config,
                            *
                        </Import-Package>
                        ...
                    </instructions>
                </configuration>
            </plugin>
        </plugins>
    </build>
    ...
</project>

5.3.5. コード生成プラグインの追加

Web サービスプロジェクトでは通常、コードを生成する必要があります。Apache CXF には、JAX-WS フロントエンド用に 2 つの Maven プラグインが同梱されており、コード生成ステップをビルドに統合できます。プラグインの選択は、次のように、Java ファーストアプローチと WSDL ファーストアプローチのどちらを使用してサービスを開発するかによって異なります。

  • Java ファーストのアプローチcxf-java2ws-plugin プラグインを使用します。
  • WSDL ファーストのアプローチcxf-codegen-plugin プラグインを使用します。

5.3.6. OSGi 設定プロパティー

OSGi 設定管理サービスは、設定オプションを OSGi バンドルに渡すためのメカニズムを定義します。設定にこのサービスを使用する必要はありませんが、通常、バンドルアプリケーションを設定するための最も便利な方法です。Blueprint は OSGi 設定のサポートを提供し、OSGi 設定管理サービスから取得した値を使用して Blueprint ファイル内の変数を置き換えることができるようにします。

OSGi 設定プロパティーの使用方法の詳細は、「バンドルプラグインの設定」「OSGi 設定を機能追加」 を参照してください。

5.3.7. バンドルプラグインの設定

概要

バンドルプラグインを機能させるために必要な情報はほぼありません。必要なすべてのプロパティーは、デフォルト設定を使用して有効な OSGi バンドルを生成します。

デフォルト値のみを使用して有効なバンドルを作成できますが、値の一部を変更することをお勧めします。プラグインの instructions 要素内のほとんどのプロパティーを指定できます。

設定プロパティー

一般的に使用される設定プロパティーのいくつかは次のとおりです。

バンドルのシンボリック名の設定

デフォルトでは、バンドルプラグインは Bundle-SymbolicName プロパティーの値を groupId + "." + artifactId に設定します。ただし、以下の例外があります。

  • groupId にセクションが 1 つしかない (ドットがない) 場合には、クラスを含む最初のパッケージ名が返されます。

    たとえば、グループ ID が commons-logging:commons-logging の場合、バンドルのシンボリック名は org.apache.commons.logging です。

  • ArtifactIdgroupId の最後のセクションと同じ場合には、groupId が使用されます。

    たとえば、POM がグループ ID およびアーティファクト ID を org.apache.maven:maven として指定すると、バンドルのシンボリック名は org.apache.maven になります。

  • ArtifactIdgroupId の最後のセクションで始まる場合には、その部分は削除されます。

    たとえば、POM がグループ ID およびアーティファクト ID を org.apache.maven:maven-core として指定すると、バンドルのシンボリック名は org.apache.maven.core になります。

バンドルのシンボリック名に独自の値を指定するには、例5.2「バンドルのシンボリック名の設定」に示すように、プラグインの instructions 要素に Bundle-SymbolicName の子を追加します。

例5.2 バンドルのシンボリック名の設定

<plugin>
  <groupId>org.apache.felix</groupId>
  <artifactId>maven-bundle-plugin</artifactId>
  <configuration>
   <instructions>
     <Bundle-SymbolicName>${project.artifactId}</Bundle-SymbolicName>
     ...
    </instructions>
  </configuration>
</plugin>

バンドル名の設定

デフォルトでは、バンドルの名前は ${project.name} に設定されます。

バンドルの名前に独自の値を指定するには、例5.3「バンドル名の設定」に示すように、プラグインの instructions 要素に Bundle-Name の子を追加します。

例5.3 バンドル名の設定

<plugin>
  <groupId>org.apache.felix</groupId>
  <artifactId>maven-bundle-plugin</artifactId>
  <configuration>
   <instructions>
     <Bundle-Name>JoeFred</Bundle-Name>
     ...
    </instructions>
  </configuration>
</plugin>

バンドルのバージョンの設定

デフォルトでは、バンドルのバージョンは ${project.version} に設定されます。ダッシュ (-) はピリオド (.) に置き換えられ、数字は 4 桁に変換されます。たとえば、4.2-SNAPSHOT4.2.0.SNAPSHOT になります。

バンドルのバージョンに独自の値を指定するには、例5.4「バンドルのバージョンの設定」に示すように、プラグインの instructions 要素に Bundle-Version の子を追加します。

例5.4 バンドルのバージョンの設定

<plugin>
  <groupId>org.apache.felix</groupId>
  <artifactId>maven-bundle-plugin</artifactId>
  <configuration>
   <instructions>
     <Bundle-Version>1.0.3.1</Bundle-Version>
     ...
    </instructions>
  </configuration>
</plugin>

エクスポートされたパッケージの指定

デフォルトでは、OSGi マニフェストの Export-Package リストには、ローカルの Java ソースコード (src/main/java 下) のすべてのパッケージが反映されます。ただし、デフォルトのパッケージ、.、および .impl または .internal が含まれるすべてのパッケージを 除きます

重要

プラグイン設定で Private-Package 要素を使用し、エクスポートするパッケージの一覧を指定しない場合、デフォルトの動作ではバンドルの Private-Package 要素にリストされているパッケージのみが含まれます。パッケージはエクスポートされません。

デフォルトの動作では、パッケージが非常に大きくなり、非公開にしておく必要のあるパッケージがエクスポートされる可能性があります。エクスポートされるパッケージの一覧を変更するには、Export-Package の子をプラグインの instructions 要素に追加します。

Export-Package 要素は、バンドルに含まれるパッケージとエクスポートされるパッケージの一覧を指定します。パッケージ名は、* ワイルドカードシンボルを使用して指定できます。たとえば、エントリー com.fuse.demo.* は、プロジェクトのクラスパスにある com.fuse.demo で始まるすべてのパッケージが含まれます。

除外するパッケージを指定するには、エントリーに ! の接頭辞を追加します。たとえば、エントリー !com.fuse.demo.private は、パッケージ com.fuse.demo.private を除外します。

パッケージを除外する場合に、リスト内のエントリーの順序が重要です。リストは最初から順番に処理され、それ以降の矛盾するエントリーは無視されます。

たとえば、パッケージ com.fuse.demo.private を除く com.fuse.demo で始まるすべてのパッケージを含めるには、以下のようにパッケージのリストを指定します。

!com.fuse.demo.private,com.fuse.demo.*

ただし、com.fuse.demo.*,!com.fuse.demo.private を使用してパッケージを一覧表示すると、com.fuse.demo.private は最初のパターンと一致するため、バンドルに含まれます。

プライベートパッケージの指定

バンドルに追加するパッケージの一覧を指定してそれらをエクスポート しない 場合、バンドルプラグイン設定に Private-Package 命令を追加できます。デフォルトでは、Private-Package 命令を指定しないと、ローカルの Java ソースのすべてのパッケージがバンドルに含まれます。

重要

パッケージが Private-Package 要素と Export-Package 要素の両方のエントリーと一致する場合は、Export-Package 要素が優先されます。パッケージがバンドルに追加され、エクスポートされます。

Private-Package 要素は、バンドルに含まれるパッケージの一覧を指定する点で Export-Package 要素と同様に機能します。バンドルプラグインは、リストを使用して、バンドルに含まれるプロジェクトのクラスパスにあるすべてのクラスを検索します。これらのパッケージはバンドルにパッケージ化されますが、(Export-Package 命令で選択されない限り) エクスポートされません。

例5.5「プライベートパッケージのバンドルへの追加」 はバンドルにプライベートパッケージを含めるための設定です。

例5.5 プライベートパッケージのバンドルへの追加

<plugin>
  <groupId>org.apache.felix</groupId>
  <artifactId>maven-bundle-plugin</artifactId>
  <configuration>
   <instructions>
     <Private-Package>org.apache.cxf.wsdlFirst.impl</Private-Package>
     ...
    </instructions>
  </configuration>
</plugin>

インポートされたパッケージの指定

デフォルトでは、バンドルプラグインは OSGi マニフェストの Import-Package プロパティーに、バンドルのコンテンツによって参照されるすべてのパッケージのリストを反映させます。

ほとんどのプロジェクトでは通常、デフォルトの動作で十分ですが、リストに自動的に追加されないパッケージをインポートする場合があります。デフォルトの動作では、不要なパッケージがインポートされる可能性もあります。

バンドルによってインポートされるパッケージの一覧を指定するには、Import-Package の子をプラグインの instructions 要素に追加します。パッケージ一覧の構文は、Export-Package 要素および Private-Package 要素の場合と同じです。

重要

Import-Package 要素を使用する場合、必要なインポートの有無を判断するのにプラグインはバンドルの内容を自動的にスキャンしません。バンドルの内容がスキャンされるようにするには、パッケージリストの最後のエントリーとして * を配置する必要があります。

例5.6「バンドルでインポートされたパッケージの指定」 は、バンドルでインポートされたパッケージを指定する設定です。

例5.6 バンドルでインポートされたパッケージの指定

<plugin>
  <groupId>org.apache.felix</groupId>
  <artifactId>maven-bundle-plugin</artifactId>
  <configuration>
   <instructions>
     <Import-Package>javax.jws, javax.wsdl, org.apache.cxf.bus, org.apache.cxf.bus.spring, org.apache.cxf.bus.resource, org.apache.cxf.configuration.spring, org.apache.cxf.resource, org.springframework.beans.factory.config, * </Import-Package>
     ...
   </instructions>
  </configuration>
</plugin>

補足情報

バンドルプラグインの設定の詳細には、以下を参照してください。

5.3.8. OSGI configAdmin ファイルの命名規則

PID 文字列 (シンボリックネーム構文) を使用すると、OSGI 仕様でハイフンを使用できます。ただし、ハイフンは Apache Felix.fileinstall および config:edit シェルコマンドによって解釈され、マネージドサービスとマネージドサービスファクトリーを区別します。したがって、PID 文字列の他の場所ではハイフンを使用しないことをお勧めします。

注記

設定ファイル名は、PID およびファクトリー PID に関連しています。