Apache Karaf へのデプロイ

Red Hat Fuse 7.9

アプリケーションパッケージを Apache Karaf コンテナーにデプロイします。

概要

本ガイドでは、アプリケーションを Apache Karaf コンテナーにデプロイするためのオプションについて説明します。

多様性を受け入れるオープンソースの強化

Red Hat では、コード、ドキュメント、Web プロパティーにおける配慮に欠ける用語の置き換えに取り組んでいます。まずは、マスター (master)、スレーブ (slave)、ブラックリスト (blacklist)、ホワイトリスト (whitelist) の 4 つの用語の置き換えから始めます。この取り組みは膨大な作業を要するため、今後の複数のリリースで段階的に用語の置き換えを実施して参ります。詳細は、CTO である Chris Wright のメッセージ をご覧ください。

パート I. 開発者ガイド

このパートには、開発者向けの情報が含まれています。

第1章 OSGi の概要

概要

OSGi 仕様は、複雑なアプリケーションの構築、デプロイ、および管理を単純化するランタイムフレームワークを定義することで、モジュラーアプリケーションの開発をサポートします。

1.1. 概要

Apache Karaf は、バンドルのデプロイおよび管理を行うための OSGi ベースのランタイムコンテナーです。また、Apache Karaf はネイティブオペレーティングシステムのインテグレーションも提供し、ライフサイクルがオペレーティングシステムにバインドされているように、サービスとしてオペレーティングシステムに統合できます。

Apache Karaf の構造は次のとおりです。

  • Apache Karaf - OSGi コンテナー実装に関するラッパーレイヤーであり、OSGi コンテナーをランタイムサーバーとしてデプロイするためのサポートを提供します。Fuse が提供するランタイム機能には、ホットデプロイメントおよび管理機能が含まれます。
  • OSGi Framework - 依存関係やバンドルのライフサイクルの管理など、OSGi 機能を実装します。

1.2. Apache Karaf のアーキテクチャー

Apache Karaf は、以下の機能で OSGi レイヤーを拡張します。

  • コンソール - コンソールはサービスを管理し、アプリケーションやライブラリーをインストールおよび管理し、Fuse ランタイムと対話します。これにより、Fuse のインスタンスを管理するためのコンソールコマンドが提供されます。『Apache Karaf Console Reference』を参照してください。
  • ロギング - logging サブシステムは、ログレベルを表示、表示、および変更するためのコンソールコマンドを提供します。
  • デプロイメント - bundle:install および bundle:start コマンドを使用した OSGi バンドルの手動デプロイメントと、アプリケーションのホットデプロイメントの両方をサポートします。「ホットデプロイメント」 を参照してください。
  • プロビジョニング - アプリケーションとライブラリーをインストールするための複数のメカニズムを提供します。9章機能のデプロイ を参照してください。
  • 設定 - InstallDir/etc フォルダーに保存されるプロパティーファイルは継続的に監視され、それらの変更は自動的に設定可能な間隔で関連するサービスに伝播されます。
  • Blueprint - OSGi コンテナーとの対話を簡素化する依存性注入フレームワークです。たとえば、OSGi サービスをインポートおよびエクスポートする標準の XML 要素を提供します。Blueprint 設定ファイルがホットデプロイメントフォルダーにコピーされると、Red Hat Fuse はその場で OSGi バンドルを生成し、Blueprint コンテキストをインスタンス化します。

1.3. OSGi Framework

1.3.1. 概要

OSGi Alliance は、OSGi Service Platform Release 4 の機能を定義する独立した組織です。OSGi Service Platform は、複雑なソフトウェアアプリケーションの構築、デプロイ、および管理を簡素化する一連のオープン仕様です。

OSGi テクノロジーは、Java の動的モジュールシステムとも呼ばれます。OSGi は、モジュール化された Java コンポーネントをデプロイし、依存関係、バージョン管理、クラスパス制御、およびクラスローディングを処理する Java のフレームワークです。OSGi のライフサイクル管理により、JVM をシャットダウンせずにバンドルをロード、開始、および停止できます。

OSGi は、Java に最適なランタイムプラットフォーム、優れたクラスローディングアーキテクチャー、およびサービスのレジストリーを提供します。バンドルはサービスをエクスポートし、プロセスを実行し、それらの依存関係を管理できます。各バンドルには、OSGi コンテナーによって管理される要件を指定できます。

Fuse は Apache Felix をデフォルトの OSGi 実装として使用します。フレームワークレイヤーは、バンドルをインストールするコンテナーを形成します。フレームワークは、動的でスケーラブルな方法でバンドルのインストールおよび更新を管理し、バンドルとサービス間の依存関係を管理します。

1.3.2. OSGi アーキテクチャー

OSGi フレームワークには、以下が含まれます。

  • バンドル - アプリケーションを構成する論理モジュール。「OSGi バンドル」 を参照してください。
  • サービスレイヤー -モジュールおよびそれに含まれるコンポーネント間の通信を提供します。このレイヤーは、ライフサイクルレイヤーと密接に統合されています。「OSGi サービス」 を参照してください。
  • ライフサイクルレイヤー - 基礎となる OSGi フレームワークへのアクセスを提供します。このレイヤーは個別のバンドルのライフサイクルを処理するため、バンドルの開始や停止などのアプリケーションを動的に管理できます。
  • モジュールレイヤー - バンドルのパッケージ化、依存関係の解決、およびクラスローディングを管理するための API を提供します。
  • 実行環境 - JVM の設定。この環境では、バンドルが機能できる環境を定義するプロファイルが使用されます。
  • セキュリティーレイヤー - Java 2 セキュリティーに基づく任意のレイヤーで、追加の制約と拡張機能があります。

フレームワークの各レイヤーは、その下のレイヤーに依存します。たとえば、ライフサイクルレイヤーにはモジュールレイヤーが必要です。モジュールレイヤーは、ライフサイクルおよびサービスレイヤーなしで使用できます。

1.4. OSGi サービス

1.4.1. 概要

OSGi サービスは、名前と値のペアとして定義されたサービスプロパティーを持つ Java クラスまたはサービスインターフェースです。サービスプロパティーは、同じサービスインターフェースでサービスを提供するサービスプロバイダー間で区別されます。

OSGi サービスは、そのサービスインターフェースでセマンティック的に定義され、サービスオブジェクトとして実装されます。サービスの機能は、サービスが実装するインターフェースによって定義されます。したがって、異なるアプリケーションが同じサービスを実装できます。

サービスインターフェースは、実装ではなく、インターフェースをバインドして、バンドルが対話できるようにします。サービスインターフェイスは、実装の詳細をできるだけ少なくして指定する必要があります。

1.4.2. OSGi サービスレジストリー

OSGi フレームワークでは、パブリッシュ、検索、およびバインドサービスモデルを使用して 「OSGi バンドル」 と含まれるコンポーネントとの間の通信を提供します。サービスレイヤーには、次のようなサービスレジストリーが含まれています。

  • サービスプロバイダーは、他のバンドルによって使用されるフレームワークにサービスを登録します。
  • サービスリクエスターはサービスを見つけ、サービスプロバイダーにバインドします。

サービスはバンドルによって所有され、バンドル内で実行されます。バンドルは、1 つ以上の Java インターフェース下のフレームワークサービスレジストリーでサービスの実装を登録します。そのため、サービスの機能はフレームワークの制御下にある他のバンドルで利用可能であり、他のバンドルはサービスを検索および使用できます。検索は、Java インターフェースおよびサービスプロパティーを使用して実行されます。

各バンドルは、そのインターフェースとプロパティーの完全修飾名を使用して、サービスレジストリーの複数のサービスを登録できます。バンドルは LDAP 構文の名前とプロパティーを使用して、サービスのサービスレジストリーをクエリーします。

バンドルは、公開、検出、バインドなどの、ランタイムサービスの依存関係管理アクティビティーを担当します。バンドルは、バンドルにバインドされるサービスの動的な可用性 (到着または出発) から生じる変更にも適用できます。

イベント通知

サービスインターフェースは、バンドルによって作成されたオブジェクトによって実装されます。バンドルは以下を行うことができます。

  • サービスの登録
  • サービスの検索
  • 登録状態が変化したときに通知を受け取る

OSGi フレームワークはイベント通知メカニズムを提供するため、サービスレジストリーの変更が発生したときにサービスリクエスターが通知イベントを受信できます。これらの変更には、特定サービスの公開または取得、およびサービスが登録、変更、または登録解除された場合が含まれます。

サービス呼び出しモデル

バンドルがサービスを使用する場合は、サービスを検索し、通常の Java 呼び出しとして Java オブジェクトを呼び出します。そのため、サービスの呼び出しは同期され、同じスレッドで実行されます。より非同期の処理のためにコールバックを使用できます。パラメーターは Java オブジェクト参照として渡されます。XMLの場合のように、マーシャリングや中間の正規形式は必要ありません。OSGi は、サービスが利用できない問題の解決策を提供します。

OSGi フレームワークサービス

独自のサービスに加えて、OSGi フレームワークは、フレームワークの操作を管理するために以下の任意のサービスを提供します。

  • パッケージ管理サービス - 共有パッケージの状態を調べて、管理エージェントは Java パッケージ共有を管理するポリシーを定義できます。また、管理エージェントはパッケージを更新でき、必要に応じてバンドルを停止および再起動することもできます。このサービスは、エクスポートバンドルがアンインストールまたは更新されたときに、管理エージェントが共有パッケージに対して意思決定できるようにします。

    このサービスでは、最終更新以降に削除または更新されたエクスポート済みパッケージを更新する方法や、特定のバンドルを明示的に解決する方法も提供します。このサービスは、実行時にバンドル間の依存関係を追跡することもできるため、アップグレードによって影響を受ける可能性のあるバンドルを確認できます。

  • 開始レベルサービス: 管理エージェントを有効にして、バンドルの開始および停止順序を制御します。サービスは、各バンドルに開始レベルを割り当てます。管理エージェントはバンドルの開始レベルを変更し、フレームワークのアクティブな開始レベルを設定して、適切なバンドルを開始および停止します。このアクティブな開始レベル以下の開始レベルを持つバンドルのみがアクティブになります。
  • URL Handlers サービス - URL スキームとコンテンツハンドラーで Java ランタイムを動的に拡張し、任意のコンポーネントが追加の URL ハンドラーを提供できるようにします。
  • Permission Adminサービス - OSGi フレームワーク管理エージェントを有効にして、特定のバンドルのパーミッションを管理し、すべてのバンドルのデフォルトを提供します。バンドルには、特権コードの実行が許可されていることを確認するために使用される単一のパーミッションのセットを含めることができます。ポリシーをその場で変更したり、新たにインストールしたコンポーネントに新しいポリシーを追加したりすることで、パーミッションを動的に操作できます。ポリシーファイルは、バンドルで実行できることを制御するために使用されます。
  • Conditional Permission Admin サービス - パーミッションがチェックされたときに特定の条件が true または false の場合に適用できるパーミッションを使用して、パーミッション管理サービスを拡張します。これらの条件により、パーミッションが適用されるバンドルの選択が決まります。パーミッションは、設定直後にアクティベートされます。

OSGi フレームワークサービスは、OSGi Alliance Web サイトの リリリース 4 ダウンロードページ から利用できる OSGi Service Platform Release 4 仕様の個別の章で詳細に説明されています。

OSGi Compendium サービス

OSGi フレームワークサービスに加えて、OSGi Alliance は任意の標準化された compendium サービスのセットを定義します。OSGi compendium サービスは、ロギングや設定などのタスクの API を提供します。これらのサービスは、OSGi Alliance Web サイトの リリース 4 ダウンロードページ から利用できる OSGi Service Platform, Service Compendium で説明されています。

Configuration Admin compendium サービスは、設定情報を永続化し、対象者に分散する中央ハブのようなものです。Configuration Admin サービスは、デプロイされたバンドルの設定情報を指定し、アクティブな場合にバンドルがそのデータを受信するようにします。バンドルの設定データは名前と値のペアの一覧です。「Apache Karaf のアーキテクチャー」 を参照してください。

1.5. OSGi バンドル

概要

OSGi を使用すると、アプリケーションをバンドルにモジュール化できます。各バンドルは密結合で、外部依存関係を明示的に宣言するクラス、JAR、および設定ファイルの動的にロード可能なコレクションです。OSGi では、バンドルはプライマリーデプロイメント形式です。バンドルは JAR でパッケージ化されるアプリケーションで、インストール、開始、停止、更新、および削除できます。

OSGi は、バンドルを開発するために動的および簡潔で、一貫性のあるプログラミングモデルを提供します。開発およびデプロイメントは、サービスの指定 (Java インターフェース) をその実装から切り離することで単純化されます。

OSGi バンドル抽象化により、モジュールは Java クラスを共有できます。これは、再利用の静的形式です。共有クラスは、依存するバンドルの開始時に利用可能である必要があります。

バンドルは、OSGi マニフェストファイルのメタデータが含まれる JAR ファイルです。バンドルにはクラスファイルが含まれ、オプションで他のリソースおよびネイティブライブラリーが含まれます。バンドル内のどのパッケージが外部で確認できるか (エクスポートされたパッケージ)、およびバンドルに必要な外部パッケージ (インポートされたパッケージ) を明示的に宣言できます。

モジュールレイヤーは、バンドル間での Java パッケージのパッケージ化と共有、および他のバンドルからのパッケージの非表示を処理します。OSGi フレームワークは、バンドル間で依存関係を動的に解決します。フレームワークは、インポートおよびエクスポートされたパッケージと一致するバンドルの解決を実行します。また、複数のバージョンのデプロイされたバンドルを管理することもできます。

OSGi でのクラスローディング

OSGi は、 (JVM で使用される) ツリーモデルではなく、クラスローディングにグラフモデルを使用します。バンドルは、実行時にクラスローディングの競合を発生せずに、標準化された方法でクラスを共有および再利用できます。

各バンドルには独自の内部クラスパスがあるため、必要な場合は独立したユニットとして機能できます。

OSGi でのクラスローディングの利点は次のとおりです。

  • バンドル間でクラスを直接共有します。JAR を親クラスローダーに昇格する必要はありません。
  • 同じクラスの異なるバージョンを、競合することなく同時にデプロイできます。

第2章 Apache Karaf の起動および停止

概要

Apache Karaf は、サーバーを起動および停止するためのシンプルなコマンドラインツールを提供します。

2.1. Apache Karaf の起動

Apache Karaf ランタイムをデプロイするデフォルトの方法は、アクティブなコンソールでスタンドアロンサーバーとしてデプロイすることです。コンソールなしでランタイムをバックグラウンドプロセスとしてデプロイすることもできます。

2.1.1. 環境の設定

環境を変更せずに、インストールの bin サブディレクトリーから直接 Karaf ランタイムを起動できます。しかし、別のフォルダーで起動する場合は、以下のように Karaf インストールの bin ディレクトリーを PATH 環境変数に追加する必要があります。

Windows

set PATH=%PATH%;InstallDir\bin

Linux/UNIX

export PATH=$PATH,InstallDir/bin`

2.1.2. コンソールモードでのランタイムの起動

インストールディレクトリーから Karaf ランタイムを起動する場合は、以下のコマンドを使用します。

Windows

bin\fuse.bat

Linux/UNIX

./bin/fuse

Karaf が正常に起動すると、コンソールに以下が表示されます。

Red Hat Fuse starting up. Press Enter to open the shell now...
100% [========================================================================]

Karaf started in 8s. Bundle stats: 220 active, 220 total

 ____          _   _   _       _     _____
|  _ \ ___  __| | | | | | __ _| |_  |  ___|   _ ___  ___
| |_) / _ \/ _` | | |_| |/ _` | __| | |_ | | | / __|/ _ \
|  _ <  __/ (_| | |  _  | (_| | |_  |  _|| |_| \__ \  __/
|_| \_\___|\__,_| |_| |_|\__,_|\__| |_|   \__,_|___/___|

  Fuse (7.x.x.fuse-xxxxxx-redhat-xxxxx)
  http://www.redhat.com/products/jbossenterprisemiddleware/fuse/

Hit '<tab>' for a list of available commands
and '[cmd] --help' for help on a specific command.

Open a browser to http://localhost:8181/hawtio to access the management console

Hit '<ctrl-d>' or 'shutdown' to shutdown Red Hat Fuse.

karaf@root()>
注記

バージョン Fuse 6.2.1 以降、コンソールモードで起動すると、2 つのプロセスが作成されます。それらは、Karaf コンソールを実行している親プロセス ./bin/karaf と、java JVM で Karaf サーバーを実行している子プロセスです。ただし、シャットダウンの動作は以前と同じです。つまり、両方のプロセスを強制終了する Ctrl-D または osgi:shutdown のいずれかを使用して、コンソールからサーバーをシャットダウンできます。

2.1.3. サーバーモードでのランタイムの起動

サーバーモードで起動すると、ローカルコンソールなしでバックグラウンドで ApacheKaraf が実行されます。次に、リモートコンソールを使用して実行中のインスタンスに接続します。詳細は 「リモートでの接続と切断」 を参照してください。

サーバーモードで Karaf を起動するには、以下を実行します。

Windows

bin\start.bat

Linux/UNIX

./bin/start

2.1.4. クライアントモードでのランタイムの起動

実稼働環境では、ローカルコンソールのみを使用してランタイムインスタンスにアクセスする必要がある場合があります。つまり、SSH コンソールポートを介してランタイムにリモートで接続することはできません。これを行うには、次のコマンドを使用して、クライアントモードでランタイムを起動します。

Windows

bin\fuse.bat client

Linux/UNIX

./bin/fuse client
注記

クライアントモードで起動すると、SSH コンソールポート (通常はポート 8101) のみが抑制されます。他の Karaf サーバーポート (JMX 管理 RMI ポートなど) は通常通りに開かれます。

2.1.5. デバッグモードでの Fuse の実行

Fuse をデバッグモードで実行すると、エラーをより効率的に識別して解決するのに役立ちます。このオプションはデフォルトで無効になっています。有効にすると、Fuse はポート 5005 で JDWP ソケットを起動します。

デバッグモードで Fuse を実行する方法は 3 つあります。

2.1.5.1. Karaf 環境変数の使用

このアプローチにより、KARAF_DEBUG 環境変数 (=1) が有効になり、次にコンテナーを起動します。

$ export KARAF_DEBUG=1
$ bin/start

2.1.5.2. fuse debug の実行

このアプローチでは、suspend オプションが n (no) に設定されている debug を実行します。

$ bin/fuse debug

2.1.5.3. fuse debugs の実行

このアプローチでは、suspend オプションが y (yes) に設定されている debugs を実行します。

注記

suspend を yes に設定すると、JVM は main() の実行直前に一時停止し、デバッガーがアタッチされると実行を再開します。

$ bin/fuse debugs

2.2. Apache Karaf の停止

コンソール内からまたは stop スクリプトを使用して、Apache Karaf のインスタンスを停止できます。

2.2.1. ローカルコンソールからのインスタンスの停止

fuse または fuse client を実行して Karaf インスタンスを起動した場合、karaf> プロンプトで以下のいずれかを実行して停止できます。

  • shutdown を入力
  • Ctrl+D を押す

2.2.2. サーバーモードで実行されているインスタンスの停止

以下のように stop(.bat)InstallDir/bin ディレクトリーから呼び出すと、ローカルで実行されている Karaf インスタンス (root コンテナー) を停止できます。

Windows

bin\stop.bat

Linux/UNIX

./bin/stop

Karaf stop スクリプトによって呼び出されるシャットダウンメカニズムは、Apache Tomcat に実装されたシャットダウンメカニズムと似ています。Karaf サーバーは専用のシャットダウンポート (SSH ポートと同じではない) を開き、シャットダウンの通知を受信します。デフォルトでは、シャットダウンポートがランダムに選択されますが、必要に応じて特定のポートを使用するように設定できます。

必要に応じて、InstallDir/etc/config.properties ファイルに以下のプロパティーを設定して、シャットダウンポートをカスタマイズできます。

karaf.shutdown.port

シャットダウンポートとして使用する TCP ポートを指定します。このプロパティーを -1 に設定すると、ポートが無効になります。デフォルトは 0 (ランダムポート用) です。

注記

bin/stop スクリプトを使用してリモートホストで実行している Karaf サーバーをシャットダウンする場合は、このプロパティーをリモートホストのシャットダウンポートと同じに設定する必要があります。ただし、この設定が etc/config.properties ファイルと同じホストにある Karaf サーバーにも影響を与えることに注意してください。

karaf.shutdown.host

シャットダウンポートがバインドされるホスト名を指定します。この設定は、マルチホームホストで役立つ場合があります。デフォルトは localhost です。

注記

bin/stop スクリプトを使用してリモートホストで実行している Karaf サーバーをシャットダウンする場合は、このプロパティーをリモートホストのホスト名 (または IP アドレス) に設定する必要があります。ただし、この設定が etc/config.properties ファイルと同じホストにある Karaf サーバーにも影響を与えることに注意してください。

karaf.shutdown.port.file
Karaf インスタンスの起動後に、このプロパティーによって指定されたファイルに現在のシャットダウンポートを書き込みます。stop スクリプトは、このプロパティーで指定されたファイルを読み取り、現在のシャットダウンポートの値を検出します。デフォルトは ${karaf.data}/port です。
karaf.shutdown.command

シャットダウンをトリガーするためにシャットダウンポートに送信する必要がある UUID 値を指定します。これにより、UUID 値が秘密にされている限り、基本レベルのセキュリティーが提供されます。たとえば、この値が通常のユーザーによって読み取られないように、etc/config.properties ファイルの読み取りを保護することができます。

Apache Karafを初めて起動すると、ランダムな UUID 値が自動的に生成され、この設定が etc/config.properties ファイルの最後に書き込まれます。または、karaf.shutdown.command がすでに設定されている場合は、Karaf サーバーは既存の UUID 値を使用します (これにより、必要に応じて UUID 設定をカスタマイズできます)。

注記

bin/stop スクリプトを使用してリモートホストで実行している Karaf サーバーをシャットダウンする場合は、このプロパティーをリモートホストの karaf.shutdown.command の値と同じに設定する必要があります。ただし、この設定が etc/config.properties ファイルと同じホストにある Karaf サーバーにも影響を与えることに注意してください。

2.2.3. リモートインスタンスの停止

「リモートコンテナーの停止」 で説明されているように、リモートホストで実行しているコンテナーインスタンスを停止できます。

第3章 基本的なセキュリティー

本章では、Karaf を初めて開始する前にセキュリティーを設定する基本的な手順を説明します。デフォルトでは Karaf はセキュアですが、そのサービスにはリモートアクセスできません。本章では、Karaf によって公開されるポートへのセキュアなアクセスを有効にする方法を説明します。

3.1. 基本的なセキュリティーの設定

3.1.1. 概要

Apache Karaf ランタイムは、公開されているすべてのポートにユーザー認証が必要であり、最初にユーザーが定義されていないため、デフォルトでネットワーク攻撃から保護されています。つまり、Apache Karaf ランタイムはデフォルトではリモートアクセスできません。

ランタイムにリモートアクセスする場合は、ここで説明するように、最初にセキュリティー設定をカスタマイズする必要があります。

3.1.2. コンテナーの起動前

Karaf コンテナーへのリモートアクセスを有効にする場合は、コンテナーを起動する前にセキュアな JAAS ユーザーを作成する必要があります。

3.1.3. セキュアな JAAS ユーザーの作成

デフォルトでは、コンテナーに対して JAAS ユーザーが定義されていません。これにより、リモートアクセスは実質的に無効になります (ログインはできません)。

セキュアな JAAS ユーザーを作成するには、InstallDir/etc/users.properties ファイルを編集し、以下のように新規ユーザーフィールドを追加します。

Username=Password,admin

ここで、UsernamePassword は新しいユーザーのクレデンシャルです。admin ロールは、このユーザーに、コンテナーのすべての管理機能にアクセスするための権限を付与します。

ゼロで始まる数値のユーザー名を定義しないでください。このようなユーザー名は常にログインの試行に失敗します。これは、コンソールが使用する Karaf シェルは、入力が数値である場合に先頭のゼロを削除するためです。以下に例を示します。

karaf@root> echo 0123
123
karaf@root> echo 00.123
0.123
karaf@root>
警告

強力なパスワードでカスタムユーザーのクレデンシャルを定義することを強くお勧めします。

3.1.4. ロールベースのアクセス制御

Karaf コンテナーはロールベースアクセス制御をサポートします。このアクセス制御は、JMX プロトコル、Karaf コマンドコンソール、および Fuse Management コンソールを介したアクセスを規制します。ユーザーにロールを割り当てるときは、表3.1「アクセス制御のための標準ロール」 で説明されているアクセスレベルを提供する標準ロールのセットから選択できます。

表3.1 アクセス制御のための標準ロール

ロール説明

viewer

コンテナーへの読み取り専用アクセスを付与します。

manager

アプリケーションをデプロイおよび実行する通常のユーザーに、適切なレベルで読み書きアクセスを付与します。ただし、機密性の高いコンテナー設定へのアクセスはブロックされます。

admin

コンテナーへの無制限のアクセスを付与します。

ssh

SSH ポート経由でリモートコンソールのアクセス権限を付与します。

ロールベースのアクセス制御の詳細は、「Role-Based Access Control」を参照してください。

3.1.5. Apache Karaf コンテナーによって公開されるポート

コンテナーによって以下のポートが公開されます。

  • コンソールポート - Apache Karaf シェルコマンドを介してコンテナーインスタンスのリモート制御を有効にします。このポートはデフォルトで有効になっており、JAAS認証とSSHの両方で保護されます。
  • JMX ポート  - JMX プロトコル経由でコンテナーの管理を有効にします。このポートはデフォルトで有効になり、JAAS 認証によってセキュア化されます。
  • Web コンソールポート - Web コンソールサーブレットをホストできる組み込み Undertow コンテナーへのアクセスを提供します。デフォルトでは、Fuse Console は Undertow コンテナーにインストールされます。

3.1.6. リモートコンソールポートの有効化

以下の条件が両方とも true であれば、リモートコンソールポートにアクセスできます。

  • JAAS が、少なくとも 1 セットのログインクレデンシャルで設定されている。
  • Karaf ランタイムがクライアントモードで起動されていない (クライアントモードはリモートコンソールポートを完全に無効にするため)。

たとえば、コンテナーが実行されているマシンからリモートコンソールポートにログインするには、以下のコマンドを入力します。

./client -u Username -p Password

ここで、Username および Password は、ssh ロールを持つ JAAS ユーザーのクレデンシャルです。リモートポートを介して Karaf コンソールにアクセスする場合、権限は etc/users.properties ファイルでユーザーに割り当てられたロールによって異なります。コンソールコマンドの完全なセットにアクセスする場合は、ユーザーアカウントに admin ロールが必要です。

3.1.7. リモートコンソールポートでのセキュリティーの強化

以下の手段を使用して、リモートコンソールポートのセキュリティーを強化できます。

  • JAAS ユーザークレデンシャルに強力なパスワードが設定されているようにします。
  • X.509 証明書をカスタマイズします (Java キーストアファイル InstallDir/etc/host.key をカスタムキーペアに置き換えます)。

3.1.8. JMX ポートの有効化

JMX ポートはデフォルトで有効になっており、JAAS 認証によってセキュア化されます。JMX ポートにアクセスするには、少なくとも 1 セットのログインクレデンシャルセットで JAAS を設定しておく必要があります。JMX ポートに接続するには、JMX クライアント (例: jconsole) を開き、以下の JMX URI に接続します。

service:jmx:rmi:///jndi/rmi://localhost:1099/karaf-root

また、接続するには、有効な JAAS クレデンシャルを JMX クライアントに提供する必要もあります。

注記

一般的に、JMX URI の最後は /karaf-ContainerName の形式を取ります。コンテナー名を root から他の名前に変更する場合は、それに応じて JMX URI を変更する必要があります。

3.1.9. Fuse Console ポートでのセキュリティーの強化

Fuse Console はすでに JAAS 認証によってセキュア化されています。SSL セキュリティーを追加するには、「Undertow HTTP サーバーのセキュア化」を参照してください

第4章 Apache Karaf をサービスとしてインストール

本章では、提供されるテンプレートを使用して、Apache Karaf インスタンスをシステムサービスとして起動する方法を説明します。

4.1. 概要

サービススクリプトテンプレートを使用すると、オペレーティングシステム固有の init スクリプトを用いて Karaf インスタンスを実行できます。これらのテンプレートは、bin/contrib ディレクトリーにあります。

4.2. Karaf をサービスとして実行

karaf-service.sh ユーティリティーは、テンプレートのカスタマイズに役立ちます。このユーティリティーは、オペレーティングシステムとデフォルトの init システムを自動的に特定し、そのまま使用できる init スクリプトを生成します。また、JAVA_HOME およびその他の環境変数を設定して、環境に合わせてスクリプトをカスタマイズすることもできます。

生成されたスクリプトは 2 つのファイルで構成されます。

  • init スクリプト
  • init 設定ファイル

4.3. systemd

karaf-service.sh ユーティリティーが systemd を特定すると、3 つのファイルが生成されます。

  • ルート Apache Karaf コンテナーを管理する systemd ユニットファイル。
  • ルート Apache Karaf コンテナーによって使用される変数が含まれる systemd 環境ファイル。
  • (サポート対象外) Apache Karaf の子コンテナーを管理するための systemd テンプレートユニットファイル。

たとえば、/opt/karaf-4 にインストールされた Karaf インスタンスのサービスを設定するには、サービスに karaf-4 という名前を付けます。

$ ./karaf-service.sh -k /opt/karaf-4 -n karaf-4
Writing service file "/opt/karaf-4/bin/contrib/karaf-4.service"
Writing service configuration file ""/opt/karaf-4/etc/karaf-4.conf"
Writing service file "/opt/karaf-4/bin/contrib/karaf-4@.service"
$ sudo cp /opt/karaf-4/bin/contrib/karaf-4.service /etc/systemd/system
$ sudo systemctl enable karaf-4.service

4.4. SysV

karaf-service.sh ユーティリティーによって SysV システムが特定されると、以下の 2 つのファイルが生成されます。

  • ルート Apache Karaf コンテナーを管理する init スクリプト。
  • ルート Apache Karaf コンテナーによって使用される変数が含まれる環境ファイル。

たとえば、/opt/karaf-4 にインストールされた Karaf インスタンスのサービスを設定するには、サービスに karaf-4 という名前を付けます。

$ ./karaf-service.sh -k /opt/karaf-4 -n karaf-4
Writing service file "/opt/karaf-4/bin/contrib/karaf-4"
Writing service configuration file "/opt/karaf-4/etc/karaf-4.conf"
$ sudo ln -s /opt/karaf-4/bin/contrib/karaf-4 /etc/init.d/
$ sudo chkconfig karaf-4 on
注記

起動時にサービスの開始を有効にするには、オペレーティングシステムの init ガイドを参照してください。

4.5. Solaris SMF

karaf-service.sh ユーティリティーによって Solaris オペレーティングシステムが特定されると、単一のファイルが生成されます。

たとえば、/opt/karaf-4 にインストールされた Karaf インスタンスのサービスを設定するには、サービスに karaf-4 という名前を付けます。

$ ./karaf-service.sh -k /opt/karaf-4 -n karaf-4
Writing service file "/opt/karaf-4/bin/contrib/karaf-4.xml"
$ sudo svccfg validate /opt/karaf-4/bin/contrib/karaf-4.xml
$ sudo svccfg import /opt/karaf-4/bin/contrib/karaf-4.xml
注記

生成された SMF 記述子は一時的なものとして定義されるため、start メソッドを実行できるのは 1 度のみです。

4.6. Windows

Windows サービスとしての Apache Karaf のインストールは、winsw を介してサポートされます。

Apache Karaf を Windows サービスとしてインストールするには、以下の手順を実行します。

  1. karaf-service-win.exe ファイルの名前を karaf-4.exe に変更します。
  2. karaf-service-win.xml ファイルの名前を karaf-4.xml に変更します。
  3. 必要に応じてサービス記述子をカスタマイズします。
  4. サービス実行ファイルを使用して、サービスをインストールし、起動、および停止します。

以下に例を示します。

C:\opt\apache-karaf-4\bin\contrib> karaf-4.exe install
C:\opt\apache-karaf-4\bin\contrib> karaf-4.exe start

4.7. karaf-service.sh オプション

karaf-service.sh ユーティリティーのオプションは、以下のようにコマンドラインオプションとして指定するか、環境変数を設定して指定します。

コマンドラインオプション環境変数説明

-k

KARAF_SERVICE_PATH

Karaf のインストールパス

-d

KARAF_SERVICE_DATA

Karaf のデータパス (デフォルトは ${KARAF_SERVICE_PATH}/data)

-c

KARAF_SERVICE_CONF

Karaf 設定ファイル (デフォルトは ${KARAF_SERVICE_PATH}/etc/${KARAF_SERVICE_NAME}.conf)

-t

KARAF_SERVICE_ETC

Karaf etc パス (デフォルトは ${KARAF_SERVICE_PATH}/etc})

-p

KARAF_SERVICE_PIDFILE

Karaf PID パス (デフォルトは ${KARAF_SERVICE_DATA}/${KARAF_SERVICE_NAME}.pid)

-n

KARAF_SERVICE_NAME

Karaf サービス名 (デフォルトは karaf)

-e

KARAF_ENV

サービス用に環境変数設定 NAME=VALUE を指定します (複数回の指定が可能)

-u

KARAF_SERVICE_USER

Karaf ユーザー

-g

KARAF_SERVICE_GROUP

Karaf グループ (デフォルトは ${KARAF_SERVICE_USER})

-l

KARAF_SERVICE_LOG

Karaf コンソールのログ (デフォルトは ${KARAF_SERVICE_DATA}/log/${KARAF_SERVICE_NAME}-console.log)

-f

KARAF_SERVICE_TEMPLATE

使用するテンプレートファイル

-x

KARAF_SERVICE_EXECUTABLE

Karaf 実行可能ファイル名 (デフォルトは karaf 、daemon および stop コマンドをサポートする必要あり)

-h

 

ヘルプメッセージ

第5章 OSGi バンドルのビルド

概要

本章では、Maven を使用して OSGi バンドルを構築する方法を説明します。バンドルを構築する場合、Maven バンドルプラグインはOSGi バンドルヘッダーの生成を自動化できるため、重要な役割を果たします (そうでなければ面倒な作業になります)。完全なサンプルプロジェクトを生成する Maven archetype も、バンドルプロジェクトの開始点を提供できます。

5.1. バンドルプロジェクトの生成

5.1.1. Maven アーキタイプでのバンドルプロジェクトの生成

迅速に開始できるようにするため、Maven アーキタイプを呼び出して、Maven プロジェクトの初期概要を生成します (Maven アーキタイプはプロジェクトウィザードに似ています)。以下の Maven アーキタイプは、OSGi バンドルをビルドするためのプロジェクトを生成します。

5.1.2. Apache Camel アーキタイプ

Apache Camel OSGi archetype は、OSGi コンテナーにデプロイできるルートを構築するプロジェクトを作成します。

以下の例は、Maven アーキタイプコマンドに座標 GroupId:ArtifactId:Version を使用して camel-blueprint プロジェクトを生成する方法を表しています。

mvn archetype:generate \
 -DarchetypeGroupId=org.apache.camel.archetypes \
 -DarchetypeArtifactId=camel-archetype-blueprint \
 -DarchetypeVersion=2.23.2.fuse-790054-redhat-00001

このコマンドの実行後、Maven は GroupIdArtifactId、および Version を指定するよう要求します。

5.1.3. バンドルのビルド

デフォルトでは、前述のアーキタイプは新しいディレクトリーにプロジェクトを作成します。その名前は指定したアーティファクト ID ArtifactId と同じです。新規プロジェクトで定義されたバンドルをビルドするには、コマンドプロンプトを開いてプロジェクトディレクトリー (つまり pom.xml ファイルが含まれるディレクトリー) に移動し、以下の Maven コマンドを入力します。

mvn install

このコマンドは、すべての Java ソースファイルをコンパイルし、ArtifactId/target ディレクトリーの下にバンドル JAR を生成した後、ローカルの Maven リポジトリーで生成された JAR をインストールします。

5.2. 既存の Maven プロジェクトの変更

5.2.1. 概要

すでに Maven プロジェクトがあり、OSGi バンドルを生成するように変更する場合は、以下の手順を実行します。

5.2.2. パッケージタイプの bundle への変更

プロジェクトの pom.xml ファイルでパッケージタイプを bundle に変更して、OSGi バンドルを生成するよう Maven を設定します。以下の例のように、packaging 要素の内容を bundle に変更します。

<project ... >
  ...
  <packaging>bundle</packaging>
  ...
</project>

この設定により、Maven バンドルプラグイン maven-bundle-plugin を選択され、このプロジェクトのパッケージ化が実行されます。ただし、この設定自体は、バンドルプラグインを POM に明示的に追加するまで効果がありません。

5.2.3. バンドルプラグインの POM への追加

Maven バンドルプラグインを追加するには、以下のサンプル plugin 要素をコピーし、プロジェクトの pom.xml ファイルの project/build/plugins セクションに貼り付けます。

<project ... >
  ...
  <build>
    <defaultGoal>install</defaultGoal>
    <plugins>
      ...
    <plugin>
        <groupId>org.apache.felix</groupId>
        <artifactId>maven-bundle-plugin</artifactId>
        <version>3.3.0</version>
        <extensions>true</extensions>
        <configuration>
          <instructions>
            <Bundle-SymbolicName>${project.groupId}.${project.artifactId}
            </Bundle-SymbolicName>
            <Import-Package>*</Import-Package>
          </instructions>
        </configuration>
      </plugin>
    </plugins>
  </build>
  ...
</project>

バンドルプラグインは instructions 要素の設定によって設定されます。

5.2.4. バンドルプラグインのカスタマイズ

Apache CXF のバンドルプラグインの設定に関する具体的な推奨事項は、「バンドルでの Web サービスのパッケージ化」 を参照してください。

5.2.5. JDK コンパイラーバージョンのカスタマイズ

ほとんどの場合、POM ファイルに JDK バージョンを指定する必要があります。コードが汎用、静的インポートなどの Java 言語の最新の機能を使用し、POM の JDK バージョンをカスタマイズしていない場合、Maven はソースコードのコンパイルに失敗します。JAVA_HOME および PATH 環境変数を JDK の正しい値に設定するだけでは不十分で、POM ファイルも変更する必要があります。

JDK 1.8 で導入された Java 言語機能を受け入れるように POM ファイルを設定するには、以下の maven-compiler-plugin プラグイン設定を POM に追加します (存在しない場合)。

<project ... >
  ...
  <build>
    <defaultGoal>install</defaultGoal>
    <plugins>
      ...
      <plugin>
        <groupId>org.apache.maven.plugins</groupId>
        <artifactId>maven-compiler-plugin</artifactId>
        <configuration>
          <source>1.8</source>
          <target>1.8</target>
        </configuration>
      </plugin>
    </plugins>
  </build>
  ...
</project>

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

5.3.1. 概要

このセクションでは、プロジェクトが Red Hat Fuse OSGi コンテナーでのデプロイメントに適した OSGi バンドルを生成するように、Apache CXF アプリケーションの既存の Maven プロジェクトを変更する方法について説明します。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-first アプローチを使用してサービスを開発するかどうかによって異なります。

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

5.3.6. OSGi 設定プロパティー

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

OSGi 設定プロパティーの使用方法は、「Bundle プラグインの設定」 および 「OSGi 設定の機能への追加」 を参照してください。

5.3.7. Bundle プラグインの設定

概要

バンドルプラグインが機能するために必要な情報はほとんどありません。必要なすべてのプロパティーは、デフォルト設定を使用して有効な 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 に関連します。

第6章 ホットデプロイメントと手動デプロイメント

概要

Fuse は、ファイルをデプロイするための 2 つの方法を提供し、それらはホットデプロイメントと手動デプロイメントです。関連バンドルのコレクションをデプロイする必要がある場合は、それらを単一としてではなく、機能 としてデプロイすることが推奨されます (9章機能のデプロイ を参照)。

6.1. ホットデプロイメント

6.1.1. ホットデプロイディレクトリー

Fuse は FUSE_HOME/deploy ディレクトリーのファイルを監視し、このディレクトリーにすべてをホットデプロイします。ファイルがこのディレクトリーにコピーされるたびに、ランタイムにインストールされ、起動されます。その後、FUSE_HOME/deploy ディレクトリーのファイルを更新または削除でき、変更は自動的に処理されます。

たとえば、バンドルProjectDir/target/foo-1.0-SNAPSHOT.jar をビルドしたばかりの場合、以下のように FUSE_HOME/deploy ディレクトリーにコピーして、このバンドルをデプロイできます (UNIX プラットフォームで作業していると仮定します)。

% cp ProjectDir/target/foo-1.0-SNAPSHOT.jar FUSE_HOME/deploy

6.2. バンドルのホットアンデプロイメント

ホットデプロイディレクトリーからバンドルをアンデプロイするには、Apache Karaf コンテナーの実行中に、バンドルファイルを FUSE_HOME/deploy ディレクトリーから削除するだけです。

重要

ホットアンデプロイの仕組みは、コンテナーがシャットダウンしている間は機能しません。Karaf コンテナーをシャットダウンしたら、FUSE_HOME/deploy ディレクトリーからバンドルファイルを削除してから、Karaf コンテナーを再起動すると、バンドルはコンテナーの再起動後にアンデプロイされません

bundle:uninstall コンソールコマンドを使用してバンドルをアンデプロイすることもできます。

6.3. 手動デプロイメント

6.3.1. 概要

Fuse コンソールでコマンドを実行して、バンドルを手動でデプロイおよびアンデプロイできます。

6.3.2. バンドルのインストール

bundle:install コマンドを使用して、OSGi コンテナーに 1 つ以上のバンドルをインストールします。このコマンドの構文は以下のとおりです。

bundle:install [-s] [--start] [--help] UrlList

UrlList は、デプロイする各バンドルの場所を指定する URL の空白区切りリストです。以下のコマンド引数がサポートされます。

-s
インストール後にバンドルを開始します。
--start
-s と同じ
--help
コマンド構文を表示および説明します。

たとえば、バンドル ProjectDir/target/foo-1.0-SNAPSHOT.jar をインストールして起動するには、Karaf コンソールプロンプトで以下のコマンドを入力します。

bundle:install -s file:ProjectDir/target/foo-1.0-SNAPSHOT.jar
注記

Windows プラットフォームでは、このコマンドの file URL に正しい構文を使用するように注意する必要があります。詳しくは、「ファイル URL ハンドラー」 を参照してください。

6.3.3. バンドルのアンインストール

バンドルをアンインストールするには、まず bundle:list コマンドを使用してそのバンドル ID を取得する必要があります。次に、bundle:uninstall コマンドを使用してバンドルをアンインストールできます (バンドル ID を引数として取ります)。

たとえば、A Camel OSGi Service Unit という名前のバンドルをすでにインストールしている場合は、コンソールプロンプトで bundle:list を入力すると、以下のような出力が生成されます。

...
[ 181] [Resolved   ] [            ] [       ] [   60] A Camel OSGi Service Unit (1.0.0.SNAPSHOT)

以下のコンソールコマンドを入力して、ID 181 でバンドルをアンインストールできるようになります。

bundle:uninstall 181

6.3.4. バンドルを見つけるための URL スキーム

bundle:install コマンドにロケーション URL を指定する場合、Fuse によってサポートされる URL スキームを使用できます。これには、以下のスキーム型が含まれます。

6.4. bundle:watch を使用したバンドルの自動再デプロイ

開発者がバンドルを絶えず変更し、再構築している開発環境では、通常、バンドルを複数回再インストールする必要があります。bundle:watch コマンドを使用すると、ローカルの Maven リポジトリーを監視し、ローカルの Maven リポジトリーで変更されると、すぐに自動的に特定のバンドルを再インストールするように Karaf に指示することができます。

たとえば、バンドル ID 751 を持つ特定のバンドルの場合、次のコマンドを入力して、自動最デプロイメントを有効にできます。

bundle:watch 751

これで、Maven アーティファクトをローカルの Maven リポジトリーに再ビルドし、インストールするたびに (Maven プロジェクトで mvn install を実行するなど)、Karaf コンテナーは変更した Maven アーティファクトを自動的に再インストールします。詳細は『Apache Karaf Console Reference』を参照してください。

重要

bundle:watch コマンドは、開発環境のみでの使用を目的としています。実稼働環境での使用は推奨されません

第7章 ライフサイクル管理

7.1. バンドルのライフサイクルの状態

OSGi 環境のアプリケーションは、そのバンドルのライフサイクルの対象となります。バンドルには 6 つのライフサイクルの状態があります。

  1. インストール済み (Installed) : すべてのバンドルは、インストールされた状態で開始されます。インストールされた状態のバンドルは、すべての依存関係を解決されるまで待機し、解決されたら、バンドルが解決済み状態に切り替わります。
  2. 解決済み (Resolved) : バンドルは、以下の条件が満たされると解決済みの状態に移動します。

    • ランタイムの環境は、バンドルで指定された環境に適合するか、それ以上となります。
    • バンドルによってインポートされたすべてのパッケージは、解決済み状態であるバンドルか、現在のバンドルと同時に解決済みの状態に移行するバンドルによって公開されます。
    • 必須バンドルはすべて解決済み状態であるか、現在のバンドルと同時に解決できます。

      重要

      アプリケーションバンドルはすべて、アプリケーションを起動する前に解決済みの状態である必要があります。

      上記の条件のいずれかが満たされない場合、バンドルはインストール済み状態に戻されます。たとえば、これは、インポートされたパッケージを含むバンドルがコンテナーから削除されると発生する可能性があります。

  3. 開始 (Starting): 開始状態は、解決済み状態とアクティブ状態の間の一時的な状態です。バンドルの起動時に、コンテナーはバンドルのリソースを作成する必要があります。また、提供されている場合、コンテナーはバンドルのバンドルアクティベーターの start() メソッドも呼び出します。
  4. アクティブ (Active): アクティブ状態の作業に使用できます。バンドルがアクティブ状態で行う作業は、バンドルの内容によって異なります。たとえば、JAX-WS サービスプロバイダーが含まれるバンドルは、サービスがリクエストを許可できることを示します。
  5. 停止 (Stopping): 停止状態は、アクティブ状態と解決済み状態の間の一時的な状態です。バンドルが停止すると、コンテナーはバンドルのリソースをクリーンアップする必要があります。また、提供されている場合、コンテナーはバンドルのバンドルアクティベーターの stop() メソッドも呼び出します。
  6. アンインストール済み (Uninstalled): バンドルをアンインストールされると、解決済み状態からアンインストール済み状態に移行します。この状態のバンドルは、解決済み状態またはその他の状態に戻すことはできません。明示的に再インストールする必要があります。

アプリケーション開発者にとって最も重要なライフサイクル状態は開始状態および停止状態です。アプリケーションによってパブリッシュされるエンドポイントは、開始状態の間にパブリッシュされます。パブリッシュされたエンドポイントは、停止状態の間停止します。

7.2. バンドルのインストールおよび解決

bundle:install コマンドを使用してバンドルをインストールする場合 (-s フラグなしで) 、カーネルは指定されたバンドルをインストールし、これを解決済み状態にしようとします。バンドルの解決が何らかの理由で失敗した場合 (たとえば、その依存関係の 1 つが満たされない場合など)、カーネルはバンドルをインストール済み状態のままにします。

後で (たとえば、不足している依存関係のインストール後など)、以下のように bundle:resolve コマンドを実行し、バンドルの解決済み状態への移行を試みることができます。

bundle:resolve 181

ここでの引数 (この例では181) は、解決するバンドルの ID です。

7.3. バンドルの開始および停止

bundle:start コマンドを使用して、(インストール済み状態または解決済み状態から) 1 つ以上のバンドルを開始できます。たとえば、ID が 181、185、および 186 であるバンドルを開始するには、以下のコンソールコマンドを入力します。

bundle:start 181 185 186

bundle:stop コマンドを使用して、1 つ以上のバンドルを停止できます。たとえば、ID が 181、185、および 186 であるバンドルを停止するには、以下のコンソールコマンドを入力します。

bundle:stop 181 185 186

bundle:restart コマンドを使用して、1 つ以上のバンドルを再起動できます (つまり、開始状態から解決済み状態に移行してから、開始状態に戻ります) 。たとえば、ID が 181、185、および 186 であるバンドルを再度開始するには、以下のコンソールコマンドを入力します。

bundle:restart 181 185 186

7.4. バンドル開始レベル

開始レベルはすべてのバンドルに関連付けられます。開始レベルは、バンドルがアクティベート/開始される順序を制御する正の整数値です。低い開始レベルを持つバンドルは、開始レベルが高いバンドルよりも先に開始されます。したがって、開始レベル 1 のバンドルは最初に開始され、カーネルに属するバンドルの開始レベルは低い傾向にあります。これらのバンドルはほとんどのバンドルを実行する前提条件を提供するためです。

通常、ユーザーバンドルの開始レベルは 60 以上です。

7.5. バンドルの開始レベルの指定

bundle:start-level コマンドを使用して、特定のバンドルの開始レベルを設定します。たとえば、ID が181 のバンドルに開始レベル 70 を設定するには、次のコンソールコマンドを入力します。

bundle:start-level 181 70

7.6. システム開始レベル

OSGi コンテナー自体に開始レベルが関連付けられており、このシステム開始レベルによって、アクティブにできるバンドルとアクティブにできないバンドルが決まります。アクティブにできるのは、開始レベルがシステム開始レベル以下のバンドルのみです

現在のシステム開始レベルを検出するには、以下のようにコンソールで system:start-level を入力します。

karaf@root()> system:start-level
Level 100

システム開始レベルを変更する場合は、以下のように、新しい開始レベルを system:start-level コマンドに引数として指定します。

system:start-level 200

第8章 依存関係のトラブルシューティング

8.1. 依存関係の不足

OSGi バンドルを Red Hat Fuse コンテナーにデプロイする場合に最もよく起こる問題は、1 つまたは複数の依存関係が欠落していることです。この問題は、OSGi コンテナー内のバンドルを解決しようとすると、通常はバンドルを開始した場合の副作用として発生します。バンドルが解決 (または起動) に失敗し、ClassNotFound エラーがログに記録されます (ログを表示するには、log:display コンソールコマンドを使用するか、FUSE_HOME/data/log ディレクトリーのログファイルを確認します)。

依存関係が不足する基本的な原因は 2 つあります。必要な機能またはバンドルがコンテナーにインストールされていない場合と、バンドルのImport-Packageヘッダーである場合です。

8.2. 必要な機能またはバンドルがインストールされていない

バンドルで必要な機能およびバンドルはすべて、バンドルの解決を試行する前に OSGi コンテナーにすでにインストールされている必要があります。特に、Apache Camel にはモジュラーアーキテクチャーがあり、各コンポーネントは個別の機能としてインストールされるため、必要なコンポーネントのいずれかをインストールすることを忘れがちです。

注記

バンドルを機能としてパッケージ化することを検討してください。機能を使用することで、バンドルをすべての依存関係とともにパッケージ化できるため、それらすべてを同時にインストールされるようにすることができます。詳細は、9章機能のデプロイ を参照してください。

8.3. Import-Package ヘッダーが不完全

すべての必要な機能とバンドルがすでにインストールされ、引き続き ClassNotFound エラーが発生する場合、バンドルの MANIFEST.MF ファイルの Import-Package ヘッダーが不完全であることを意味します。maven-bundle-plugin (「既存の Maven プロジェクトの変更」 を参照) は、バンドルの Import-Package ヘッダーを生成するときには非常に便利ですが、以下の点に注意してください。

  • Maven バンドルプラグイン設定の Import-Package 要素に、ワイルドカード * が必ず含まれるようにします。ワイルドカードは、Java ソースコードをスキャンし、パッケージの依存関係の一覧を自動的に生成するよう、プラグインに指示します。
  • Maven バンドルプラグインは動的な依存関係を把握できません。たとえば、Java コードが明示的にクラスローダーを呼び出してクラスを動的にロードする場合、バンドルプラグインはこれを考慮せず、必要な Java パッケージは生成された Import-Package ヘッダーにリストされません。
  • Blueprint XML ファイル (例: OSGI-INF/blueprint ディレクトリー) を定義する場合、Blueprint XML ファイルからの依存関係はすべて、ランタイム時に自動的に解決されます

8.4. 不足している依存関係を追跡する方法

不足している依存関係を追跡するには、以下の手順を実行します。

  1. bundle:diag コンソールコマンドを使用します。これにより、バンドルが非アクティブである理由に関する情報が提供されます。使用法については、『Apache Karaf Console Reference』を参照してください。
  2. クイックチェックを実行して、必要なすべてのバンドルと機能が実際にOSGiコンテナーにインストールされていることを確認します。bundle:list を使用してインストールされたバンドルをチェックでき、features:list を使用してどの機能がインストールされているかをチェックできます。
  3. bundle:install コンソールコマンドを使用して、バンドルをインストールします (ただし、開始しません)。以下に例を示します。

    karaf@root()> bundle:install MyBundleURL
  4. bundle:dynamic-import コンソールコマンドを使用して、インストールしたばかりのバンドルで動的インポートを有効にします。たとえば、バンドルのバンドル ID が 218 の場合、以下のコマンドを入力してこのバンドルで動的インポートを有効にします。

    karaf@root()> bundle:dynamic-import 218

    この設定により、コンテナーにすでにインストールされているバンドルのいずれかを使用して依存関係を解決し、通常の依存関係解決メカニズム (Import-Package ヘッダーに基づく) を効果的に迂回できます。これはバージョンチェックをバイパスするため、通常のデプロイメントにはお勧めしません。間違ったバージョンを簡単に取得でき、アプリケーションが誤動作する可能性があります。

  5. これでバンドルを解決できるようになります。たとえば、バンドル ID が 218 の場合は、以下の コンソールコマンドを入力します。

    karaf@root()> bundle:resolve 218
  6. バンドルが解決されたと仮定した場合 (bundle:list でバンドルのステータスを確認)、package:imports コマンドを使用して、バンドルに結び付けた全パッケージの完全なリストを取得することができます。たとえば、バンドル ID が 218 の場合、以下のコンソールコマンドを入力します。

    karaf@root()> package:imports -b 218

    コンソールウィンドウで、依存パッケージの一覧が表示されます。

    Package                              │ Version       │ Optional   │ ID  │ Bundle Name
    ─────────────────────────────────────┼───────────────┼────────────┼─────┼──────────────────────────────────
    org.apache.jasper.servlet            │ [2.2.0,3.0.0) │ resolved   │ 217 │ org.ops4j.pax.web.pax-web-runtime
    org.jasypt.encryption.pbe            │               │ resolved   │ 217 │ org.ops4j.pax.web.pax-web-runtime
    org.ops4j.pax.web.jsp                │ [7.0.0,)      │ resolved   │ 217 │ org.ops4j.pax.web.pax-web-runtime
    org.ops4j.pax.web.service.spi.model  │ [7.0.0,)      │            │ 217 │ org.ops4j.pax.web.pax-web-runtime
    org.ops4j.pax.web.service.spi.util   │ [7.0.0,)      │            │ 217 │ org.ops4j.pax.web.pax-web-runtime
    ...
  7. バンドル JAR ファイルを展開し、META-INF/MANIFEST.MF ファイルの Import-Package ヘッダーの下に表示されているパッケージを確認します。この一覧を、前の手順で確認したパッケージの一覧と比較します。ここで、マニフェストの Import-Package ヘッダーで欠落しているパッケージの一覧をコンパイルし、これらのパッケージ名をプロジェクトの POM ファイルの Maven バンドルプラグイン設定の Import-Package 要素に追加します。
  8. 動的インポートオプションをキャンセルするには、OSGi コンテナーから古いバンドルをアンインストールする必要があります。たとえば、バンドル ID が 218 の場合、以下のコマンドを入力します。

    karaf@root()> bundle:uninstall 218
  9. インポートされたパッケージの更新されたリストでバンドルを再構築し、OSGi コンテナーでテストできるようになりました。

addurl :experimental: :toc: :toclevels: 4 :numbered:

第9章 機能のデプロイ

概要

アプリケーションおよびその他のツールは、通常複数の OSGi バンドルから構成されるため、相互依存または関連するバンドルをより大きなデプロイメント単位に集約すると便利なことがよくあります。したがって、Red Hat Fuseは、スケーラブルなデプロイメントの単位である機能を提供します。これにより、複数のバンドル (およびオプションで他の機能への依存関係) を単一のステップでデプロイできます。

9.1. 機能の作成

9.1.1. 概要

基本的に、 eatures リポジトリー として知られる特別な種類の XML ファイルに新しい feature 要素を追加して機能が作成されます。機能を作成するには、以下の手順を実施します。

9.2. カスタム features リポジトリーの作成

カスタム features リポジトリーを定義していない場合は、以下のように作成できます。ファイルシステム上で機能ポジトリーに便利な場所を選択します。たとえば、C:\Projects\features.xml などです。テキストエディターを使用して、以下の行を追加します。

<?xml version="1.0" encoding="UTF-8"?>
<features name="CustomRepository">
</features>

ここでは、name 属性を設定して、リポジトリーの名前 CustomRepository を指定する必要があります。

注記

Maven リポジトリーまたは OBR とは対照的に、features リポジトリーはバンドルの保存場所を提供しません。features リポジトリーは、バンドルへの参照の集合を格納するだけです。バンドル自体は別の場所に保存されます (例: ファイルシステムや Maven リポジトリー内) 。

9.3. カスタム features リポジトリーへの機能の追加

カスタム features リポジトリーに機能を追加するには、新しい feature 要素をルート features 要素の子として挿入します。機能に名前を付ける必要があります。bundle 子要素を挿入することで、機能に属するバンドルをいくつでもリストできます。たとえば、単一のバンドルを含む example-camel-bundle という名前の機能 C:\Projects\camel-bundle\target\camel-bundle-1.0-SNAPSHOT.jar を追加するには、以下のように feature 要素を追加します。

<?xml version="1.0" encoding="UTF-8"?>
<features name="MyFeaturesRepo">
  <feature name="example-camel-bundle">
    <bundle>file:C:/Projects/camel-bundle/target/camel-bundle-1.0-SNAPSHOT.jar</bundle>
  </feature>
</features>

bundle 要素の内容は有効な URL で、バンドルの場所を示す任意の有効なURLにすることができます (15章URL ハンドラー を参照) 。必要に応じて、機能要素で version 属性を指定して、機能にゼロ以外のバージョンを割り当てることができます (これにより、バージョンを features:install コマンドに任意の引数として指定できます) 。

機能サービスが新しい機能エントリーを正しく解析するかどうかを確認するには、以下のコンソールコマンドのペアを入力します。

JBossFuse:karaf@root> features:refreshurl
JBossFuse:karaf@root> features:list
...
[uninstalled] [0.0.0                 ] example-camel-bundle                 MyFeaturesRepo
...

features:list コマンドは、機能のかなり長いリストを生成しますが、リストをスクロールして、新しい機能のエントリーを見つけることができるはずです (ここでは example-camel-bundle)。features:refreshurl コマンドは、カーネルにすべての features リポジトリーの再読み取りを強制します。このコマンドを実行しないと、カーネルは、リポジトリーに最近加えた変更を認識しません (特に、新しい機能はリストに表示されません)。

機能の長いリストでスクロールしないようにするには、以下のように example-camel-bundle 機能の grep を使用します。

JBossFuse:karaf@root> features:list | grep example-camel-bundle
[uninstalled] [0.0.0                 ] example-camel-bundle                 MyFeaturesRepo

grep コマンド (標準の UNIX パターン一致ユーティリティー) がシェルに組み込まれるため、このコマンドは Windows プラットフォームでも機能します。

9.4. ローカルリポジトリー URL の機能サービスへの追加

新しい features リポジトリーを Apache Karaf で利用可能にするには、features:addurl コンソールを使用して features リポジトリーを追加する必要があります。たとえば、C:\Projects\features.xml リポジトリーの内容をカーネルで利用できるようにするには、次のコンソールコマンドを入力します。

features:addurl file:C:/Projects/features.xml

features:addurl への引数は、サポートされる URL 形式を使用して指定できます (15章URL ハンドラー を参照)。

以下のように features:listUrl コンソールコマンドを入力して、登録されたすべての features リポジトリーの URL の完全なリストを取得して、リポジトリーの URL が正常に登録されていることを確認します。

JBossFuse:karaf@root> features:listUrl
file:C:/Projects/features.xml
mvn:org.apache.ode/ode-jbi-karaf/1.3.3-fuse-01-00/xml/features
mvn:org.apache.felix.karaf/apache-felix-karaf/1.2.0-fuse-01-00/xml/features

9.5. 機能への依存機能の追加

この機能が他の機能に依存している場合は、feature 要素を元の feature 要素の子として追加することで、これらの依存関係を指定できます。各 feature 子要素には、現在の機能が依存する機能の名前が含まれます。依存関係機能で機能をデプロイすると、依存機能がコンテナーにインストールされているかどうかが確認されます。そうでない場合は、依存関係メカニズムにより、不足している依存関係 (および再帰的な依存関係) が自動的にインストールされます。

たとえば、カスタムの Apache Camel 機能 example-camel-bundle では、依存する標準の Apache Camel 機能を明示的に指定できます。OSGi コンテナーに必要な機能が事前デプロイされていない場合でも、アプリケーションを正常にデプロイして実行できるという利点があります。たとえば、以下のように Apache Camel 依存関係で example-camel-bundle 機能を定義できます。

<?xml version="1.0" encoding="UTF-8"?>
<features name="MyFeaturesRepo">
  <feature name="example-camel-bundle">
    <bundle>file:C:/Projects/camel-bundle/target/camel-bundle-1.0-SNAPSHOT.jar</bundle>
    <feature version="7.9.0.fuse-790071-redhat-00001">camel-core</feature>
    <feature version="7.9.0.fuse-790071-redhat-00001">camel-spring-osgi</feature>
  </feature>
</features>

version 属性の指定は任意です。存在する場合は、この機能の指定されたバージョンを選択できます。

9.6. OSGi 設定の機能への追加

アプリケーションが OSGi Configuration Admin サービスを使用する場合は、機能定義の config 子要素を使用して、このサービスの設定を指定できます。たとえば、prefix プロパティーの値が MyTransform であることを指定するには、以下の config 子要素を機能の設定に追加します。

<?xml version="1.0" encoding="UTF-8"?>
<features name="MyFeaturesRepo">
  <feature name="example-camel-bundle">
    <config name="org.fusesource.fuseesb.example">
      prefix=MyTransform
    </config>
  </feature>
</features>

config 要素の name 属性は、プロパティー設定の永続 ID を指定します (永続 ID は実質的にプロパティー名の名前スコープとして機能します) 。config 要素の内容は、Java プロパティーファイルと同じ方法で解析されます。

config 要素の設定は、以下のように、永続 ID にしたがって命名される InstallDir/etc ディレクトリーにある Java プロパティーファイルの設定によって、オプションで上書きできます。

InstallDir/etc/org.fusesource.fuseesb.example.cfg

上記の設定プロパティーを使用する方法の例として、OSGi 設定プロパティーにアクセスする以下の Blueprint XML ファイルを見てみましょう。

<?xml version="1.0" encoding="UTF-8"?>
<blueprint xmlns="http://www.osgi.org/xmlns/blueprint/v1.0.0"
           xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
           xmlns:cm="http://aries.apache.org/blueprint/xmlns/blueprint-cm/v1.1.0">

    <!-- osgi blueprint property placeholder -->
    <cm:property-placeholder id="placeholder"
                             persistent-id="org.fusesource.fuseesb.example">
        <cm:default-properties>
            <cm:property name="prefix" value="DefaultValue"/>
        </cm:default-properties>
    </cm:property-placeholder>

    <bean id="myTransform" class="org.fusesource.fuseesb.example.MyTransform">
      <property name="prefix" value="${prefix}"/>
    </bean>

</blueprint>

この Blueprint XML ファイルが example-camel-bundle バンドルにデプロイされると、プロパティー参照 ${prefix} は、 features リポジトリーの config 要素で指定される値 MyTransform に置き換えられます。

9.7. OSGi 設定の自動デプロイ

configfile 要素を機能に追加すると、この機能がインストールされると同時に OSGi 設定ファイルが InstallDir/etc ディレクトリーに追加されるようにすることができます。これは、機能とそれに関連する設定を同時にインストールできることを意味します。

たとえば、org.fusesource.fuseesb.example.cfg 設定ファイルが mvn:org.fusesource.fuseesb.example/configadmin/1.0/cfg の Maven リポジトリーでアーカイブされている場合、以下の要素を機能に追加するとこの設定ファイルをデプロイできます。

<configfile finalname="etc/org.fusesource.fuseesb.example.cfg">
  mvn:org.fusesource.fuseesb.example/configadmin/1.0/cfg
</configfile>

第10章 機能のデプロイ

10.1. 概要

この機能は以下のいずれかの方法でデプロイできます。

  • features:install を使用して、コンソールにインストールします。
  • ホットデプロイメントを使用します。
  • ブート設定を変更します (初回ブートのみ) 。

10.2. コンソールでのインストール

(features リポジトリーにエントリーを追加し、 features リポジトリーを登録することで) 機能を作成した後、features:install コンソールを使用して機能を比較的簡単にデプロイできます。たとえば、example-camel-bundle 機能をデプロイするには、以下のコンソールコマンドのペアを入力します。

JBossFuse:karaf@root> features:refreshurl
JBossFuse:karaf@root> features:install example-camel-bundle

features リポジトリーの機能に対して最近変更が加えられ、カーネルがまだ認識していない場合は、features:install を呼び出す会えに features:refreshurl コマンドを呼び出すことが推奨されます。features:install コマンドは、機能名を引数として取ります (オプションで 2 番目の引数として機能バージョンを取ります) 。

注記

機能は、フラットな namespace を使用します。したがって、機能の命名時に、名前が既存の機能と競合しないように注意してください。

10.3. コンソールでのアンインストール

機能をアンインストールするには、以下のように features:uninstall コマンドを実行します。

JBossFuse:karaf@root> features:uninstall example-camel-bundle
注記

アンインストール後、features:list を呼び出すと機能は引き続き表示されますが、そのステータスには [uninstalled] のフラグが付けられます。

10.4. ホットデプロイメント

features リポジトリーファイルを InstallDir/deploy ディレクトリーにコピーするだけで、すべての機能を features リポジトリーにホットデプロイできます。

features リポジトリー全体を一度にホットデプロイする可能性は低いため、縮小された features リポジトリーを定義したり、デプロイする機能のみを参照する機能記述子を定義したりする方が便利な場合がよくあります。機能記述子の構文は features リポジトリーとまったく同じですが、異なるスタイルで記述されます。違いは、機能記述子は features リポジトリーから既存の機能への参照のみで構成されることです。

たとえば、以下のように example-camel-bundle 機能を読み込む機能記述子を定義できます。

<?xml version="1.0" encoding="UTF-8"?>
<features name="CustomDescriptor">
  <repository>RepositoryURL</repository>
  <feature name="hot-example-camel-bundle">
    <feature>example-camel-bundle</feature>
  </feature>
</features>

repository 要素は、カスタム機能のリポジトリー RepositoryURL の場所を指定します (ここでは、15章URL ハンドラー に記載されている URL 形式のいずれかを使用できます) 。機能 hot-example-camel-bundle は、既存の機能 example-camel-bundle への参照です。

10.5. features ファイルのホットアンデプロイ

ホットデプロイディレクトリーから features ファイルをアンデプロイするには、Apache Karaf コンテナーの実行中に、features ファイルを InstallDir/deploy ディレクトリーから削除するだけです。

重要

ホットアンデプロイの仕組みは、コンテナーがシャットダウンしている間は機能しません。Karaf コンテナーをシャットダウンした場合はdeploy/ から機能ファイルを削除してから、Karaf コンテナーを再起動すると、コンテナーの再起動後にその機能はアンデプロイされません (ただし、features:uninstall コンソールコマンドを使用してその機能を手作業でアンデプロイできます) 。

10.6. ブート設定への機能の追加

複数のホストにデプロイするために Apache Karaf のコピーをプロビジョニングする場合は、ブート設定に機能を追加することをお勧めします。これにより、Apache Karaf が初めて起動するときにインストールされる機能のコレクションが決まります。

インストールディレクトリーの設定ファイル /etc/org.apache.karaf.features.cfg には、以下の設定が含まれます。

...
#
# Comma separated list of features repositories to register by default
#
featuresRepositories = \
    mvn:org.apache-extras.camel-extra.karaf/camel-extra/2.21.0.fuse-000032-redhat-2/xml/features, \
    mvn:org.apache.karaf.features/spring-legacy/4.2.0.fuse-000191-redhat-1/xml/features, \
    mvn:org.apache.activemq/artemis-features/2.4.0.amq-710008-redhat-1/xml/features, \
    mvn:org.jboss.fuse.modules.patch/patch-features/7.0.0.fuse-000163-redhat-2/xml/features, \
    mvn:org.apache.karaf.features/framework/4.2.0.fuse-000191-redhat-1/xml/features, \
    mvn:org.jboss.fuse/fuse-karaf-framework/7.0.0.fuse-000163-redhat-2/xml/features, \
    mvn:org.apache.karaf.features/standard/4.2.0.fuse-000191-redhat-1/xml/features, \
    mvn:org.apache.karaf.features/enterprise/4.2.0.fuse-000191-redhat-1/xml/features, \
    mvn:org.apache.camel.karaf/apache-camel/2.21.0.fuse-000055-redhat-2/xml/features, \
    mvn:org.apache.cxf.karaf/apache-cxf/3.1.11.fuse-000199-redhat-1/xml/features, \
    mvn:io.hawt/hawtio-karaf/2.0.0.fuse-000145-redhat-1/xml/features

#
# Comma separated list of features to install at startup
#
featuresBoot = \
    instance/4.2.0.fuse-000191-redhat-1, \
    cxf-commands/3.1.11.fuse-000199-redhat-1, \
    log/4.2.0.fuse-000191-redhat-1, \
    pax-cdi-weld/1.0.0, \
    camel-jms/2.21.0.fuse-000055-redhat-2, \
    ssh/4.2.0.fuse-000191-redhat-1, \
    camel-cxf/2.21.0.fuse-000055-redhat-2, \
    aries-blueprint/4.2.0.fuse-000191-redhat-1, \
    cxf/3.1.11.fuse-000199-redhat-1, \
    cxf-http-undertow/3.1.11.fuse-000199-redhat-1, \
    pax-jdbc-pool-narayana/1.2.0, \
    patch/7.0.0.fuse-000163-redhat-2, \
    cxf-rs-description-swagger2/3.1.11.fuse-000199-redhat-1, \
    feature/4.2.0.fuse-000191-redhat-1, \
    camel/2.21.0.fuse-000055-redhat-2, \
    jaas/4.2.0.fuse-000191-redhat-1, \
    camel-jaxb/2.21.0.fuse-000055-redhat-2, \
    camel-paxlogging/2.21.0.fuse-000055-redhat-2, \
    deployer/4.2.0.fuse-000191-redhat-1, \
    diagnostic/4.2.0.fuse-000191-redhat-1, \
    patch-management/7.0.0.fuse-000163-redhat-2, \
    bundle/4.2.0.fuse-000191-redhat-1, \
    kar/4.2.0.fuse-000191-redhat-1, \
    camel-csv/2.21.0.fuse-000055-redhat-2, \
    package/4.2.0.fuse-000191-redhat-1, \
    scr/4.2.0.fuse-000191-redhat-1, \
    maven/4.2.0.fuse-000191-redhat-1, \
    war/4.2.0.fuse-000191-redhat-1, \
    camel-mail/2.21.0.fuse-000055-redhat-2, \
    fuse-credential-store/7.0.0.fuse-000163-redhat-2, \
    framework/4.2.0.fuse-000191-redhat-1, \
    system/4.2.0.fuse-000191-redhat-1, \
    pax-http-undertow/6.1.2, \
    camel-jdbc/2.21.0.fuse-000055-redhat-2, \
    shell/4.2.0.fuse-000191-redhat-1, \
    management/4.2.0.fuse-000191-redhat-1, \
    service/4.2.0.fuse-000191-redhat-1, \
    camel-undertow/2.21.0.fuse-000055-redhat-2, \
    camel-blueprint/2.21.0.fuse-000055-redhat-2, \
    camel-spring/2.21.0.fuse-000055-redhat-2, \
    hawtio/2.0.0.fuse-000145-redhat-1, \
    camel-ftp/2.21.0.fuse-000055-redhat-2, \
    wrap/2.5.4, \
    config/4.2.0.fuse-000191-redhat-1, \
    transaction-manager-narayana/5.7.2.Final

この設定ファイルには 2 つのプロパティーがあります。

  • featuresRepositories - 起動時に読み込む features リポジトリーのコンマ区切りリスト。
  • featuresBoot - 起動時にインストールする機能のコンマ区切りリスト。

設定を変更して、Fuse の起動時にインストールされる機能をカスタマイズできます。Fuse が事前にインストールされた機能で配布される予定である場合は、この設定ファイルを変更することもできます。

重要

この機能を追加する方法は、特定の Apache Karaf インスタンスが初めて起動する場合にのみ有効となります。その後に featuresRepositories 設定および featuresBoot 設定に加えられた変更は、コンテナーを再起動しても無視されます。

ただし、InstallDir/data/cache の内容全体を削除することで、コンテナーを強制的に初期状態に戻すことができます (これにより、コンテナーのカスタム設定がすべて失われます)。

第11章 プレーン JAR のデプロイ

概要

Apache Karaf にアプリケーションをデプロイする別の方法は、プレーン JAR ファイルを使用することです。これらは通常、デプロイメントメタデータを含まないライブラリーです。プレーン JAR は WAR や OSGi バンドルでもありません。

プレーン JAR がバンドルの依存関係として発生する場合は、バンドルヘッダーを JAR に追加する必要があります。JAR がパブリック API を公開する場合、通常、既存の JAR をバンドルに変換して、JAR を他のバンドルと共有できるようにするのが最適な解決方法です。本章の手順に従って、オープンソース Bnd ツールを使用して変換プロセスを自動的に実行します。

Bnd ツールの詳細は、Bnd ツール の Web サイトを参照してください。

11.1. ラップスキームを使用した JAR の変換

概要

wrap: プロトコルを使用して JAR をバンドルに変換するオプションがあり、既存の URL 形式で使用できます。wrap: プロトコルは Bnd ユーティリティーに基づいています。

構文

wrap: プロトコルの基本的な構文は次のとおりです。

wrap:LocationURL

wrap: プロトコルは、JAR を特定する URL にプレフィックスとして指定できます。URL の一部を見つけるため、プレーン JAR と wrap: プロトコルの URL ハンドラーをの取得に LocationURL が使用され、JAR が自動的にバンドルに変換されます。

注記

wrap: プロトコルは、より詳細な構文もサポートします。これにより、Bnd プロパティーファイルを指定するか、URL に個別の Bnd プロパティーを指定して、変換をカスタマイズできます。ただし、通常は、wrap: プロトコルがデフォルト設定で使用されます。

デフォルトのプロパティー

wrap: プロトコルは Bnd ユーティリティーをベースとしているため、Bnd とまったく同じデフォルトプロパティーを使用してバンドルを生成します

Wrap および install

以下の例は、単一のコンソールコマンドを使用して、リモート Maven リポジトリーからプレーン commons-logging JAR をダウンロードし、これを OSGi バンドルに動的に変換してから、OSGi コンテナーで起動する方法を示しています。

karaf@root> bundle:install -s wrap:mvn:commons-logging/commons-logging/1.1.1

リファレンス

wrap: プロトコルは、Pax プロジェクトによって提供されます。これは、さまざまなオープンソースの OSGi ユーティリティー向けの包括的なプロジェクトです。wrap: プロトコルに関するドキュメントは、Wrap Protocol リファレンスページを参照してください。

第12章 OSGi サービス

概要

OSGi コアフレームワークは、OSGi サービスレジストリーで Java オブジェクトをサービスとして登録することで、バンドルが対話する簡単なメカニズムを提供する OSGi Service Layer を定義します。OSGi サービスモデルの長所の 1 つは、任意の Java オブジェクトをサービスとして提供できることです。サービスクラスに適用する必要のある特定の制約、継承ルール、またはアノテーションはありません。本章では、OSGi Blueprint コンテナーを使用して OSGi サービスをデプロイする方法を説明します。

12.1. Blueprint コンテナー

概要

Blueprint コンテナーは、OSGi コンテナーとの対話を簡素化する依存性注入フレームワークです。Blueprint コンテナーは、OSGi サービスレジストリーを使用する設定ベースのアプローチをサポートします。たとえば、OSGi サービスをインポートおよびエクスポートするための標準の XML 要素を提供します。

12.1.1. Blueprint の設定

JAR ファイルの Blueprint ファイルの場所

バンドル JAR ファイルのルートを基準にすると、Blueprint 設定ファイルの標準の場所は次のディレクトリーです。

OSGI-INF/blueprint

このディレクトリー下の .xml が付いたファイルはすべて、Blueprint 設定ファイルとして解釈されます。つまり、パターン OSGI-INF/blueprint/*.xml に一致するファイルがこれに該当します。

Maven プロジェクトの Blueprint ファイルの場所

Maven プロジェクト ProjectDir のコンテキストでは、Blueprint 設定ファイルの標準的な場所は次のディレクトリーです。

ProjectDir/src/main/resources/OSGI-INF/blueprint

Blueprint namespace とルート要素

Blueprint の設定要素は、以下の XML namespace に関連付けられています。

http://www.osgi.org/xmlns/blueprint/v1.0.0

Blueprint 設定のルート要素は blueprint であるため、通常、Blueprint XML 設定ファイルには以下のようなアウトライン形式になります。

<?xml version="1.0" encoding="UTF-8"?>
<blueprint xmlns="http://www.osgi.org/xmlns/blueprint/v1.0.0">
  ...
</blueprint>
注記

blueprint ルート要素では、スキーマの場所が Blueprint フレームワークにすでに認識されているため、xsi:schemaLocation 属性を使用して Blueprint スキーマの場所を指定する必要はありません。

Blueprint マニフェストの設定

Blueprint 設定の一部の要素は、以下のように JAR のマニフェストファイル META-INF/MANIFEST.MF のヘッダーによって制御されます。

カスタムの Blueprint ファイルの場所

標準以外の場所 (つまり OSGI-INF/blueprint/*.xml 以外の場所) に Blueprint 設定ファイルを配置する必要がある場合は、マニフェストファイル内の Bundle-Blueprint ヘッダーの代替場所をコンマ区切りリストで指定できます。以下に例を示します。

Bundle-Blueprint: lib/account.xml, security.bp, cnf/*.xml

必須の依存関係

OSGi サービスの依存関係はデフォルトで必須です (ただし、reference 要素または reference-list 要素の availability 属性を optional に設定すると変更できます) 。依存関係を必須として宣言すると、バンドルはその依存関係なしで適切に機能しなくなり、依存関係が常に利用可能である必要があります。

通常、Blueprint コンテナーの初期化中、猶予期間 を経過し、その間にすべての必須の依存関係を解決しようとします。この時間内に必須の依存関係を解決できない場合 (デフォルトのタイムアウトは 5 分) 、コンテナーの初期化は中断され、バンドルは起動されません。以下の設定を Bundle-SymbolicName マニフェストヘッダーに追加して、猶予期間を設定できます。

blueprint.graceperiod
true (デフォルト) の場合、猶予期間が有効になり、Blueprint コンテナーは初期化中に必須の依存関係が解決されるのを待ちます。false の場合は、猶予期間が省略され、コンテナーが必須の依存関係が解決されているかどうかを確認しません。
blueprint.timeout
猶予期間のタイムアウトをミリ秒単位で指定します。デフォルトは 300000 (5 分) です。

たとえば、10 秒の猶予期間を有効にするには、マニフェストファイルに以下の Bundle-SymbolicName ヘッダーを定義します。

Bundle-SymbolicName: org.fusesource.example.osgi-client;
 blueprint.graceperiod:=true;
 blueprint.timeout:= 10000

Bundle-SymbolicName ヘッダーの値はセミコロン区切りのリストです。最初の項目は実際のバンドルシンボリック名で、2 番目の項目 blueprint.graceperiod:=true は猶予期間を有効にし、3 番目のアイテム blueprint.timeout:= 10000 は 10 秒のタイムアウトを指定します。

12.1.2. サービス Bean の定義

概要

Blueprint コンテナーを使用すると、bean 要素を使用して Java クラスをインスタンス化できます。このように、メインアプリケーションオブジェクトすべてを作成できます。特に、bean 要素を使用して、OSGi サービスインスタンスを表す Java オブジェクトを作成できます。

Blueprint Bean 要素

Blueprint の bean 要素は、Blueprint スキーマ namespace http://www.osgi.org/xmlns/blueprint/v1.0.0 で定義されます。

サンプル Bean

以下の例は、Blueprint の bean 要素を使用して、さまざまな種類の Bean を作成する方法を示しています。

<blueprint xmlns="http://www.osgi.org/xmlns/blueprint/v1.0.0">

  <bean id="label" class="java.lang.String">
    <argument value="LABEL_VALUE"/>
  </bean>

  <bean id="myList" class="java.util.ArrayList">
    <argument type="int" value="10"/>
  </bean>

  <bean id="account" class="org.fusesource.example.Account">
    <property name="accountName" value="john.doe"/>
    <property name="balance" value="10000"/>
  </bean>

</blueprint>

最後の Bean の例によって参照される Account クラスは以下のように定義できます。

package org.fusesource.example;

public class Account
{
    private String accountName;
    private int balance;

    public Account () { }

    public void setAccountName(String name) {
        this.accountName = name;
    }

    public void setBalance(int bal) {
        this.balance = bal;
    }
    ...
}

参考資料

Blueprint Bean の定義に関する詳細は、以下の参考資料を参照してください。

12.1.3. プロパティーを使用した Blueprint の設定

概要

ここでは、Camel コンテキスト外にあるファイルに保持されるプロパティーを使用して、Blueprint を設定する方法を説明します。

Blueprint Bean の設定

Blueprint Bean は、外部ファイルのプロパティーを置換できる変数を使用して設定できます。ext namespace を宣言し、Blueprint xml に property placeholder Bean を追加する必要があります。Property-Placeholder Bean を使用して、プロパティーファイルの場所を Blueprint に宣言します。

<blueprint xmlns="http://www.osgi.org/xmlns/blueprint/v1.0.0"
    xmlns:ext="http://aries.apache.org/blueprint/xmlns/blueprint-ext/v1.2.0">

    <ext:property-placeholder>
      <ext:location>file:etc/ldap.properties</ext:location>
    </ext:property-placeholder>
    ...
    <bean ...>
        <property name="myProperty" value="${myProperty}" />
    </bean>
</blueprint>

property-placeholder 設定オプションの指定は http://aries.apache.org/schemas/blueprint-ext/blueprint-ext.xsd にあります。

12.2. サービスのエクスポート

概要

ここでは、Java オブジェクトを OSGi サービスレジストリーにエクスポートして、OSGi コンテナーの他のバンドルへサービスとしてアクセスできるようにする方法を説明します。

単一インターフェースを使用したエクスポート

単一のインターフェース名で OSGi サービスレジストリーにサービスをエクスポートするには、ref 属性を使用して関連するサービス Bean を参照する service 要素を定義し、interface 属性を使用してパブリッシュされたインターフェースを指定します。

たとえば、例12.1「単一のインターフェースを使用したサンプルサービスのエクスポート」 に記載されている Blueprint 設定コードを使用して、org.fusesource.example.Account インターフェース名の下にある SavingsAccountImpl クラスのインスタンスをエクスポートできます。

例12.1 単一のインターフェースを使用したサンプルサービスのエクスポート

<blueprint xmlns="http://www.osgi.org/xmlns/blueprint/v1.0.0">

  <bean id="savings" class="org.fusesource.example.SavingsAccountImpl"/>

  <service ref="savings" interface="org.fusesource.example.Account"/>

</blueprint>

ref 属性は、対応する Bean インスタンスの ID を指定し、interface 属性は OSGi サービスレジストリーに登録されているパブリック Java インターフェースの名前を指定します。この例で使用されるクラスとインターフェースは、例12.2「アカウントクラスおよびインターフェースの例」 に記載されています。

例12.2 アカウントクラスおよびインターフェースの例

package org.fusesource.example

public interface Account { ... }

public interface SavingsAccount { ... }

public interface CheckingAccount { ... }

public class SavingsAccountImpl implements SavingsAccount
{
    ...
}

public class CheckingAccountImpl implements CheckingAccount
{
    ...
}

複数のインターフェースを使用したエクスポート

複数のインターフェース名の下にある OSGi サービスレジストリーにサービスをエクスポートするには、ref 属性を使用して関連するサービス Bean を参照する service 要素を定義し、interfaces 子要素を使用してパブリッシュされたインターフェースを指定します。

たとえば、以下の Blueprint 設定コードを使用すると、パブリック Java インターフェース org.fusesource.example.Account および org.fusesource.example.SavingsAccount の一覧で SavingsAccountImpl クラスのインスタンスをエクスポートできます。

<blueprint xmlns="http://www.osgi.org/xmlns/blueprint/v1.0.0">
  <bean id="savings" class="org.fusesource.example.SavingsAccountImpl"/>
  <service ref="savings">
    <interfaces>
      <value>org.fusesource.example.Account</value>
      <value>org.fusesource.example.SavingsAccount</value>
    </interfaces>
  </service>
  ...
</blueprint>
注記

interface 属性と interfaces 要素は、同じ service 要素で同時に使用できません。どちらか一方を使用する必要があります。

auto-export を使用したエクスポート

実装されたすべてのパブリック Java インターフェース下で、サービスを OSGi サービスレジストリーにエクスポートする場合には、auto-export 属性を使用してこれを簡単に実現する方法があります。

たとえば、実装されたすべてのパブリックインターフェースで SavingsAccountImpl クラスのインスタンスをエクスポートするには、以下の Blueprint 設定コードを使用します。

<blueprint xmlns="http://www.osgi.org/xmlns/blueprint/v1.0.0">
  <bean id="savings" class="org.fusesource.example.SavingsAccountImpl"/>
  <service ref="savings" auto-export="interfaces"/>
  ...
</blueprint>

auto-export 属性の値 interfaces は、Blueprint が SavingsAccountImpl によって実装されたすべてのパブリックインターフェースを登録する必要があることを示しています。auto-export 属性には、次の有効な値を指定できます。

disabled
自動エクスポートを無効にします。これがデフォルトです。
interfaces
実装されたすべてのパブリック Java インターフェースでサービスを登録します。
class-hierarchy
Object クラスを除き、独自のタイプ (クラス) およびすべてのスーパータイプ (スーパークラス) の下のサービスを登録します。
all-classes
class-hierarchy オプションと同様ですが、実装されたすべてのパブリック Java インターフェースも含まれます。

サービスプロパティーの設定

OSGi サービスレジストリーでは、サービスプロパティーを登録済みサービスに関連付けることもできます。サービスのクライアントはサービスプロパティーを使用して、サービスプロパティーを検索またはフィルタリングできます。サービスプロパティーをエクスポートしたサービスに関連付けるには、1 つ以上の beans:entry 要素が含まれる service-properties 子要素を追加します (サービスプロパティーごとに beans:entry 要素 1 つ)。

たとえば、bank.name 文字列プロパティーを普通預金口座サービスに関連付けるには、以下の Blueprint 設定を使用できます。

<blueprint xmlns="http://www.osgi.org/xmlns/blueprint/v1.0.0"
           xmlns:beans="http://www.springframework.org/schema/beans"
           ...>
  ...
  <service ref="savings" auto-export="interfaces">
    <service-properties>
      <beans:entry key="bank.name" value="HighStreetBank"/>
    </service-properties>
  </service>
  ...
</blueprint>

ここで、bank.name 文字列プロパティーには値 HighStreetBank があります。文字列以外のタイプのサービスプロパティーを定義できます。つまり、プリミティブ型、配列、コレクションもサポートされます。これらのタイプの定義方法に関する詳細は、『Spring Reference Guide』の「Controlling the Set of Advertised Properties」を参照してください。

注記

entry 要素は Blueprint namespace に属している必要があります。Spring の Blueprint 実装での beans:entry 要素の使用は標準ではありません。

デフォルトのサービスプロパティー

以下のように、service 要素を使用してサービスをエクスポートするときに自動的に設定される可能性がある 2 つのサービスプロパティーがあります。

  • osgi.service.blueprint.compname は、Bean がインライン (Bean が service 要素の子要素として定義される) の場合を除き、サービスの bean 要素の id を常に設定します。インライン化された Bean は常に匿名です。
  • service.ranking は、ranking 属性がゼロ以外である場合に自動的に設定されます。

ranking 属性の指定

バンドルがサービスレジストリーでサービスを検索し、複数の一致するサービスを見つけた場合、ランキングを使用してどのサービスが返されるかを判断できます。ルールは、検索が複数のサービスに一致する場合は常に、最高ランクのサービスが返されるというものです。サービスランクは負ではない整数で、0 がデフォルトです。service 要素に ranking 属性を設定して、サービスランクを指定できます。以下に例を示します。

<service ref="savings" interface="org.fusesource.example.Account" ranking="10"/>

登録リスナーの指定

サービス登録および登録解除イベントを追跡する場合は、登録イベントと登録解除イベントの通知を受信する登録リスナーコールバック Bean を定義できます。登録リスナーを定義するには、registration-listener 子要素を service 要素に追加します。

たとえば、以下の Blueprint 設定は、registration-listener 要素によって参照されるリスナー Bean listenerBean を定義し、Account サービスが登録または登録解除されるたびにリスナー Bean がコールバックを受信するようにします。

<blueprint xmlns="http://www.osgi.org/xmlns/blueprint/v1.0.0" ...>
  ...
  <bean id="listenerBean" class="org.fusesource.example.Listener"/>

  <service ref="savings" auto-export="interfaces">
    <registration-listener
        ref="listenerBean"
        registration-method="register"
        unregistration-method="unregister"/>
  </service>
  ...
</blueprint>

registration-listener 要素の ref 属性がリスナー Bean の id を参照する場合は、registration-method 属性は登録コールバックを受信するリスナーメソッドの名前を指定し、unregistration-method 属性は登録解除コールバックを受信するリスナーメソッドの名前を指定します。

以下の Java コードは、登録および登録解除のイベントの通知を受信する Listener クラスの定義例を示しています。

package org.fusesource.example;

public class Listener
{
    public void register(Account service, java.util.Map serviceProperties) {
        ...
    }

    public void unregister(Account service, java.util.Map serviceProperties) {
        ...
    }
}

メソッド名 registerunregister は、registration-method および unregistration-method 属性によってそれぞれ指定されます。これらのメソッドの署名は、以下の構文に準拠する必要があります。

  • 最初のメソッド引数 - サービスオブジェクトのタイプから割り当て可能なすべてのタイプ T。つまり、サービスクラスのスーパータイプクラス、またはサービスクラスによって実装されるインターフェース。サービス Bean が scopeprototype であることを宣言していない限り、この引数にはサービスインスタンスが含まれます。この場合、この引数は null です (スコープが prototype の場合、登録時に利用可能なサービスインスタンスはありません)。
  • 2 つ目のメソッド引数 - java.util.Map 型または java.util.Dictionary 型のいずれかでなければなりません。このマップには、このサービス登録に関連付けられたサービスプロパティーが含まれます。

12.3. サービスのインポート

概要

本セクションでは、OSGi サービスレジストリーにエクスポートされた OSGi サービスへの参照を取得および使用する方法を説明します。reference 要素または reference-list 要素のいずれかを使用して、OSGi サービスをインポートできます。reference 要素はステートレスサービスへのアクセスに適していますが、reference-list 要素はステートフルサービスへのアクセスに適しています。

サービス参照の管理

OSGi サービス参照を取得する以下のモデルがサポートされます。

参照マネージャー

参照マネージャーインスタンスは、Blueprint reference 要素によって作成されます。この要素は単一のサービス参照を返し、ステートレスサービスにアクセスするための推奨されるアプローチです。図12.1「ステートレスサービスへの参照」 は、参照マネージャーを使用してステートレスサービスにアクセスするためのモデルの概要を示しています。

図12.1 ステートレスサービスへの参照

deploy simple svc 01

クライアントの Blueprint コンテナーの Bean は、OSGi サービスレジストリーからサービスオブジェクト (バッキングサービス) によってバッキングされるプロキシーオブジェクト (提供済みオブジェクト) にインジェクトされます。このモデルは、以下の方法で、ステートレスサービスが相互変更可能であるという事実を明示的に利用します。

  • reference 要素の基準と一致する複数のサービスインスタンスが見つかった場合は、参照マネージャーは、バッキングインスタンスのいずれかを任意に選択することができます (交換可能であるため) 。
  • バッキングサービスが消えた場合、参照マネージャーは、同じタイプの他の利用可能なサービスの 1 つを使用するようにすぐに切り替えることができます。したがって、あるメソッド呼び出しから次のメソッド呼び出しまで、プロキシが同じバッキングサービスへの接続を維持する保証はありません。

したがって、クライアントとバッキングサービス間のコントラクトはステートレスであり、クライアントは常に同じサービスインスタンスと通信していると想定してはなりません。一致するサービスインスタンスがない場合は、ServiceUnavailable 例外をスローする前にプロキシーは一定時間待機します。タイムアウトの長さは、reference 要素に timeout 属性を設定することで設定できます。

参照リストマネージャー

参照リストマネージャーインスタンスは、Blueprint reference-list 要素によって作成されます。この要素はサービス参照のリストを返し、ステートフルサービスにアクセスするための推奨されるアプローチです。図12.2「ステートフルサービスへの参照のリスト」 は、参照リストマネージャーを使用してステートフルサービスにアクセスするためのモデルの概要を示しています。

図12.2 ステートフルサービスへの参照のリスト

deploy simple svc 02

クライアントの Blueprint コンテナーの Bean は、プロキシーオブジェクトの一覧が含まれる java.util.List オブジェクト (提供済みオブジェクト) で注入されます。各プロキシーは、OSGi サービスレジストリーの一意のサービスインスタンスによってバッキングされます。ステートレスモデルとは異なり、ここではバッキングサービスは互換性があるとは見なされません。実際、リスト内の各プロキシーのライフサイクルは、対応するバッキングサービスのライフサイクルと密接に関連しています。サービスが OSGi レジストリーに登録されると、対応するプロキシーが同期的に作成され、プロキシリストに追加されます。また、サービスが OSGi レジストリーから登録解除されると、対応するプロキシーがプロキシーリストから同期的に削除されます。

したがって、プロキシーとそのバッキングサービス間のコントラクトはステートフルであり、クライアントは、特定のプロキシーでメソッドを呼び出すときに、常に同じバッキングサービスと通信していると想定する場合があります。ただし、バッキングサービスが利用できなくなることがあり、その場合はプロキシーが古くなります。古いプロキシーでメソッドを呼び出すと、ServiceUnavailable 例外が生成されます。

インターフェースによるマッチング (ステートレス)

ステートレスサービス参照を取得する最も簡単な方法は、reference 要素の interface 属性を仕様して一致するインターフェースを指定することです。interface 属性の値がサービスのスーパータイプである場合や、属性値がサービスによって実装された Java インターフェースである場合、サービスは一致すると見なされます (interface 属性は Java クラスまたは Java インターフェースのいずれかを指定できます)。

たとえば、ステートレス SavingsAccount サービスを参照するには、以下のように reference 要素を定義します (例12.1「単一のインターフェースを使用したサンプルサービスのエクスポート」 を参照)。

<blueprint xmlns="http://www.osgi.org/xmlns/blueprint/v1.0.0">

  <reference id="savingsRef"
             interface="org.fusesource.example.SavingsAccount"/>

  <bean id="client" class="org.fusesource.example.client.Client">
    <property name="savingsAccount" ref="savingsRef"/>
  </bean>

</blueprint>

reference 要素によって ID savingsRef を持つ参照マネージャー Bean が作成されます。参照されたサービスを使用するには、以下に示すように savingsRef Bean をクライアントクラスのいずれかに注入します。

クライアントクラスにインジェクトされた bean プロパティーは、SavingsAccount から割り当て可能なあらゆるタイプにすることができます。たとえば、以下のように Client クラスを定義できます。

package org.fusesource.example.client;

import org.fusesource.example.SavingsAccount;

public class Client {
    SavingsAccount savingsAccount;

    // Bean properties
    public SavingsAccount getSavingsAccount() {
        return savingsAccount;
    }

    public void setSavingsAccount(SavingsAccount savingsAccount) {
        this.savingsAccount = savingsAccount;
    }
    ...
}

インターフェースによるマッチング (ステートフル)

ステートフルサービス参照を取得する最も簡単な方法は、reference-list 要素の interface 属性を仕様して一致するインターフェースを指定することです。その後、参照リストマネージャーはすべてのサービスのリストを取得します。interface 属性の値はサービスのスーパータイプか、またはサービスによって実装されてた Java インターフェースのいずれかです (interface 属性は Java クラスまたは Java インターフェースのいずれかを指定できます)。

たとえば、ステートフル SavingsAccount サービスを参照するには、以下のように reference-list 要素を定義します (例12.1「単一のインターフェースを使用したサンプルサービスのエクスポート」 を参照)。

<blueprint xmlns="http://www.osgi.org/xmlns/blueprint/v1.0.0">

  <reference-list id="savingsListRef"
                  interface="org.fusesource.example.SavingsAccount"/>

  <bean id="client" class="org.fusesource.example.client.Client">
    <property name="savingsAccountList" ref="savingsListRef"/>
  </bean>

</blueprint>

reference-list 要素によって ID savingsListRef を持つ参照 リストマネージャー Bean が作成されます。参照されたサービスリストを使用するには、以下に示すように savingsListRef Bean 参照をクライアントクラスのいずれかに注入します。

デフォルトでは、savingsAccountList Bean プロパティーはサービスオブジェクトのリストです (例: java.util.List<SavingsAccount>) 。以下のようにクライアントクラスを定義できます。

package org.fusesource.example.client;

import org.fusesource.example.SavingsAccount;

public class Client {
    java.util.List<SavingsAccount> accountList;

    // Bean properties
    public java.util.List<SavingsAccount> getSavingsAccountList() {
        return accountList;
    }

    public void setSavingsAccountList(
                    java.util.List<SavingsAccount> accountList
    ) {
        this.accountList = accountList;
    }
    ...
}

インターフェースおよびコンポーネント名によるマッチング

ステートレスサービスのインターフェースとコンポーネント名 (Bean ID) の両方と一致するには、以下のように interface 属性と component-name 属性を reference 要素に指定します。

<reference id="savingsRef"
           interface="org.fusesource.example.SavingsAccount"
           component-name="savings"/>

ステートフルサービスのインターフェースとコンポーネント名 (Bean ID) の両方と一致するには、以下のように interface 属性と component-name 属性を reference-list 要素に指定します。

<reference-list id="savingsRef"
           interface="org.fusesource.example.SavingsAccount"
           component-name="savings"/>

サービスプロパティーとフィルターの一致

フィルターに対してサービスプロパティーを一致することにより、サービスを選択できます。フィルターは、reference 要素または reference-list 要素で filter 属性を使用して指定されます。filter 属性の値は LDAP フィルター式である必要があります。たとえば、bank.name サービスプロパティーが HighStreetBank の場合にマッチするフィルターを定義するには、以下の LDAP フィルター式を使用します。

(bank.name=HighStreetBank)

2 つのサービスプロパティーの値を一致させるには、論理 and で式を組み合わせる & 結合を使用できます。たとえば、foo プロパティーが FooValue と等しく、bar プロパティーが BarValue と等しいことを必要とするには、以下の LDAP フィルター式を使用できます。

(&(foo=FooValue)(bar=BarValue))

LDAP フィルター式の完全な構文は、OSGi Core Specification のセクション 3.2.7 を参照してください。

フィルターは、interface および component-name 設定と組み合わせることもできます。この設定では、指定したすべての条件が一致する必要があります。

たとえば、SavingsAccount タイプのステートレスサービスHighStreetBank と等しい bank.name サービスプロパティーと一致させるには、以下のように reference 要素を定義します。

<reference id="savingsRef"
           interface="org.fusesource.example.SavingsAccount"
           filter="(bank.name=HighStreetBank)"/>

SavingsAccount タイプのステートフルサービスHighStreetBank と等しい bank.name サービスプロパティーと一致させるには、以下のように reference-list 要素を定義します。

<reference-list id="savingsRef"
           interface="org.fusesource.example.SavingsAccount"
           filter="(bank.name=HighStreetBank)"/>

必須または任意であるかの指定

デフォルトでは、OSGi サービスへの参照は必須であると想定されます (必須の依存関係を参照)。要素に availability 属性を設定して、reference 要素または reference-list 要素の依存関係動作をカスタマイズできます。

availability 属性には、可能な値が 2 つあります。

  • mandatory (デフォルト) は、通常の Blueprint コンテナーの初期化中に依存関係を解決する必要があることを意味します。
  • optional は、依存関係が初期化中に解決される必要がないことを意味します。

以下の reference 要素の例では、参照が必須の依存関係であることを明示的に宣言する方法を示しています。

<reference id="savingsRef"
           interface="org.fusesource.example.SavingsAccount"
           availability="mandatory"/>

参照リスナーの指定

たとえば、一部のサービス参照に optional が使用できることを宣言した場合など、OSGi 環境の動的な性質に対応するには、バッキングサービスがレジストリーにバインドされたときと、レジストリーからバインド解除されたときを追跡すると便利なことがよくあります。サービスバインディングおよびバインドイベントの通知を受信するには、reference-listener 要素を reference 要素または reference-list 要素の子として定義できます。

たとえば、以下の Blueprint 設定は、参照リスナーを、ID savingsRef を持つ参照マネージャーの子として定義する方法を示しています。

<blueprint xmlns="http://www.osgi.org/xmlns/blueprint/v1.0.0">

  <reference id="savingsRef"
             interface="org.fusesource.example.SavingsAccount"
             >
    <reference-listener bind-method="onBind" unbind-method="onUnbind">
      <bean class="org.fusesource.example.client.Listener"/>
    </reference-listener>
  </reference>

  <bean id="client" class="org.fusesource.example.client.Client">
    <property name="savingsAcc" ref="savingsRef"/>
  </bean>

</blueprint>

上記の設定では、bind および unbind イベントをリッスンするコールバックとして org.fusesource.example.client.Listener タイプのインスタンスを登録します。イベントは、savingsRef 参照マネージャーのバッキングサービスがバインドまたはバインド解除されるたびに生成されます。

以下の例は、Listener クラスの実装例を示しています。

package org.fusesource.example.client;

import org.osgi.framework.ServiceReference;

public class Listener {

    public void onBind(ServiceReference ref) {
        System.out.println("Bound service: " + ref);
    }

    public void onUnbind(ServiceReference ref) {
        System.out.println("Unbound service: " + ref);
    }

}

メソッド名 onBindonUnbind は、bind-method および unbind-method 属性によってそれぞれ指定されます。これらのコールバックメソッドはいずれも org.osgi.framework.ServiceReference 引数を取ります。

12.4. OSGi サービスのパブリッシュ

12.4.1. 概要

本セクションでは、OSGi コンテナーで単純な OSGi サービスを生成、ビルド、デプロイする方法を説明します。サービスは単純な Hello World の Java クラスで、OSGi 設定は Blueprint 設定ファイルを使用して定義されます。

12.4.2. 前提条件

Maven Quickstart アーキタイプを使用してプロジェクトを生成するには、以下が前提条件として必要になります。

  • Maven インストール - Maven は Apache の無料のオープンソースビルドツールです。最新バージョンは http://maven.apache.org/download.html からダウンロードできます (最小バージョンは 2.0.9) 。
  • インターネット接続 - ビルドの実行中、Maven は追加設定を必要とせずに動的に外部リポジトリーを検索し、必要なアーティファクトをダウンロードします。これが機能するためには、ビルドマシンがインターネットに接続されている必要があります。

12.4.3. Maven プロジェクトの生成

maven-archetype-quickstart アーキタイプは汎用の Maven プロジェクトを作成し、それを目的に合わせてカスタマイズできます。コーディネート org.fusesource.example:osgi-service を使用して Maven プロジェクトを生成するには、次のコマンドを入力します。

mvn archetype:create
-DarchetypeArtifactId=maven-archetype-quickstart
-DgroupId=org.fusesource.example
-DartifactId=osgi-service

このコマンドの結果は、生成されたプロジェクトのファイルが含まれるディレクトリー ProjectDir/osgi-service です。

注記

既存の製品のグループ ID と競合するアーティファクトのグループ ID を選択しないように注意してくださいこれにより、プロジェクトのパッケージと既存の製品のパッケージが競合する可能性があります (通常、グループ ID はプロジェクトの Java パッケージ名のルートとして使用されるため)。

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

OSGi バンドルを生成するには、以下のように POM ファイルをカスタマイズする必要があります。

  1. 「バンドルプロジェクトの生成」 に記載されている POM カスタマイズ手順にしたがいます。
  2. Maven バンドルプラグインの設定で、以下のようにバンドルの手順を変更して org.fusesource.example.service パッケージをエクスポートします。

    <project ... >
      ...
      <build>
        ...
        <plugins>
          ...
          <plugin>
            <groupId>org.apache.felix</groupId>
            <artifactId>maven-bundle-plugin</artifactId>
            <extensions>true</extensions>
            <configuration>
              <instructions>
                <Bundle-SymbolicName>${pom.groupId}.${pom.artifactId}</Bundle-SymbolicName>
            <Export-Package>org.fusesource.example.service</Export-Package>
              </instructions>
            </configuration>
          </plugin>
        </plugins>
      </build>
      ...
    </project>

12.4.5. サービスインターフェースの作成

ProjectDir/osgi-service/src/main/java/org/fusesource/example/service サブディレクトリーを作成します。このディレクトリーで、お気に入りのテキストエディターを使用してファイル HelloWorldSvc.java を作成し、例12.3「HelloWorldSvc インターフェース」 からコードを追加します。

例12.3 HelloWorldSvc インターフェース

package org.fusesource.example.service;

public interface HelloWorldSvc
{
    public void sayHello();
}

12.4.6. サービスクラスの作成

ProjectDir/osgi-service/src/main/java/org/fusesource/example/service/impl サブディレクトリーを作成します。このディレクトリーで、お気に入りのテキストエディターを使用してファイル HelloWorldSvcImpl.java を作成し、例12.4「HelloWorldSvcImpl クラス」 からコードを追加します。

例12.4 HelloWorldSvcImpl クラス

package org.fusesource.example.service.impl;

import org.fusesource.example.service.HelloWorldSvc;

public class HelloWorldSvcImpl implements HelloWorldSvc {

    public void sayHello()
    {
        System.out.println( "Hello World!" );
    }

}

12.4.7. Blueprint ファイルの作成

Blueprint 設定ファイルは、クラスパスの OSGI-INF/blueprint ディレクトリーに格納されている XML ファイルです。Blueprint ファイルをプロジェクトに追加するには、まず以下のサブディレクトリーを作成します。

ProjectDir/osgi-service/src/main/resources
ProjectDir/osgi-service/src/main/resources/OSGI-INF
ProjectDir/osgi-service/src/main/resources/OSGI-INF/blueprint

src/main/resources は、すべての JAR リソースの標準的な Maven の場所になります。このディレクトリーにあるリソースファイルは、生成されたバンドル JAR のルートスコープに自動的にパッケージ化されます。

例12.5「サービスをエクスポートするための Blueprint ファイル」 は、bean 要素を使用して、HelloWorldSvc Bean を作成し、 service 要素を使用して Bean を OSGi サービスとしてエクスポートする Blueprint ファイルのサンプルを示しています。

ProjectDir/osgi-service/src/main/resources/OSGI-INF/blueprint ディレクトリーで、お気に入りのテキストエディターを使用してファイル config.xml を作成し、例12.5「サービスをエクスポートするための Blueprint ファイル」 から XML コードを追加します。

例12.5 サービスをエクスポートするための Blueprint ファイル

<?xml version="1.0" encoding="UTF-8"?>
<blueprint xmlns="http://www.osgi.org/xmlns/blueprint/v1.0.0">

  <bean id="hello" class="org.fusesource.example.service.impl.HelloWorldSvcImpl"/>

  <service ref="hello" interface="org.fusesource.example.service.HelloWorldSvc"/>

</blueprint>

12.4.8. サービスバンドルの実行

osgi-service プロジェクトをインストールおよび実行するには、以下の手順を実行します。

  1. プロジェクトをビルドします - コマンドプロンプトを開き、ProjectDir/osgi-service ディレクトリーに移動します。以下のコマンドを入力して、Maven を使用してデモをビルドします。

    mvn install

    このコマンドが正常に実行されると、ProjectDir/osgi-service/target ディレクトリーにバンドルファイル osgi-service-1.0-SNAPSHOT.jar が含まれるはずです。

  2. osgi-service バンドルのインストールおよび開始 - Red Hat Fuseコンソールで、次のコマンドを入力します。

    Jkaraf@root()> bundle:install -s file:ProjectDir/osgi-service/target/osgi-service-1.0-SNAPSHOT.jar

    ProjectDir は Maven プロジェクトを含むディレクトリーで、-s フラグはバンドルをすぐに起動するように指示します。たとえば、Windows マシンのプロジェクトディレクトリーが C:\Projects の場合、以下のコマンドを入力します。

    karaf@root()> bundle:install -s file:C:/Projects/osgi-service/target/osgi-service-1.0-SNAPSHOT.jar
    注記

    Windowsマシンでは、file URL のフォーマット方法に注意してください。file URLハンドラーが認識する構文の詳細は 「ファイル URL ハンドラー」 を参照してください。

  3. サービスが作成されたことを確認します - バンドルが正常に起動したことを確認するには、以下の Red Hat Fuse コンソールコマンドを入力します。

    karaf@root()> bundle:list

    このリストのどこかに、osgi-service バンドルの行が表示されるはずです。以下に例を示します。

    [ 236] [Active     ] [Created     ] [       ] [   60] osgi-service (1.0.0.SNAPSHOT)

12.5. OSGi サービスへのアクセス

12.5.1. 概要

本セクションでは、OSGi コンテナーで単純な OSGi クライアントを生成、ビルド、デプロイする方法を説明します。クライアントは、OSGi レジストリーで単純な Hello World サービスを見つけ、そのサービスで sayHello() メソッドを呼び出します。

12.5.2. 前提条件

Maven Quickstart アーキタイプを使用してプロジェクトを生成するには、以下が前提条件として必要になります。

  • Maven インストール - Maven は Apache の無料のオープンソースビルドツールです。最新バージョンは http://maven.apache.org/download.html からダウンロードできます (最小バージョンは 2.0.9) 。
  • インターネット接続 - ビルドの実行中、Maven は追加設定を必要とせずに動的に外部リポジトリーを検索し、必要なアーティファクトをダウンロードします。これが機能するためには、ビルドマシンがインターネットに接続されている必要があります。

12.5.3. Maven プロジェクトの生成

maven-archetype-quickstart アーキタイプは汎用の Maven プロジェクトを作成し、それを目的に合わせてカスタマイズできます。コーディネート org.fusesource.example:osgi-client を使用して Maven プロジェクトを生成するには、次のコマンドを入力します。

mvn archetype:create
-DarchetypeArtifactId=maven-archetype-quickstart
-DgroupId=org.fusesource.example
-DartifactId=osgi-client

このコマンドの結果は、生成されたプロジェクトのファイルを含むディレクトリー ProjectDir/osgi-client です。

注記

既存の製品のグループ ID と競合するアーティファクトのグループ ID を選択しないように注意してくださいこれにより、プロジェクトのパッケージと既存の製品のパッケージが競合する可能性があります (通常、グループ ID はプロジェクトの Java パッケージ名のルートとして使用されるため)。

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

OSGi バンドルを生成するには、以下のように POM ファイルをカスタマイズする必要があります。

  1. 「バンドルプロジェクトの生成」 に記載されている POM カスタマイズ手順にしたがいます。
  2. クライアントは osgi-service バンドルで定義される HelloWorldSvc Java インターフェースを使用するので、osgi-service バンドルに Maven 依存関係を追加する必要があります。osgi-service バンドルの Maven コーディネートが org.fusesource.example:osgi-service:1.0-SNAPSHOT であることを想定する場合、以下の依存関係をクライアントの POM ファイルに追加する必要があります。

    <project ... >
      ...
      <dependencies>
        ...
        <dependency>
            <groupId>org.fusesource.example</groupId>
            <artifactId>osgi-service</artifactId>
            <version>1.0-SNAPSHOT</version>
        </dependency>
      </dependencies>
      ...
    </project>

12.5.5. Blueprint ファイルの作成

Blueprint ファイルをクライアントプロジェクトに追加するには、最初に以下のサブディレクトリーを作成します。

ProjectDir/osgi-client/src/main/resources
ProjectDir/osgi-client/src/main/resources/OSGI-INF
ProjectDir/osgi-client/src/main/resources/OSGI-INF/blueprint

ProjectDir/osgi-client/src/main/resources/OSGI-INF/blueprint ディレクトリーで、お気に入りのテキストエディターを使用してファイル config.xml を作成し、例12.6「サービスをインポートするための Blueprint ファイル」 から XML コードを追加します。

例12.6 サービスをインポートするための Blueprint ファイル

<?xml version="1.0" encoding="UTF-8"?>
<blueprint xmlns="http://www.osgi.org/xmlns/blueprint/v1.0.0">

  <reference id="helloWorld"
        interface="org.fusesource.example.service.HelloWorldSvc"/>

  <bean id="client"
        class="org.fusesource.example.client.Client"
        init-method="init">
    <property name="helloWorldSvc" ref="helloWorld"/>
  </bean>

</blueprint>

reference 要素は、OSGi レジストリーで HelloWorldSvc タイプのサービスを見つける参照マネージャーを作成します。bean 要素は Client クラスのインスタンスを作成し、サービス参照を Bean プロパティー helloWorldSvc として注入します。さらに、init-method 属性は、Bean の初期化フェーズ中 (つまり、サービス参照がクライアント Bean に注入された) に Client.init() メソッドが呼び出されるように指定します。

12.5.6. クライアントクラスの作成

ProjectDir/osgi-client/src/main/java/org/fusesource/example/client ディレクトリーで、お気に入りのテキストエディターを使用してファイル Client.java を作成し、例12.7「クライアントクラス」 から Java コードを追加します。

例12.7 クライアントクラス

package org.fusesource.example.client;

import org.fusesource.example.service.HelloWorldSvc;

public class Client {
    HelloWorldSvc helloWorldSvc;

    // Bean properties
    public HelloWorldSvc getHelloWorldSvc() {
        return helloWorldSvc;
    }

    public void setHelloWorldSvc(HelloWorldSvc helloWorldSvc) {
        this.helloWorldSvc = helloWorldSvc;
    }

    public void init() {
        System.out.println("OSGi client started.");
        if (helloWorldSvc != null) {
            System.out.println("Calling sayHello()");
            helloWorldSvc.sayHello();  // Invoke the OSGi service!
        }
    }

}

Client クラスは helloWorldSvc Bean プロパティーの getter メソッドおよび setter メソッドを定義します。これによりインジェクションによる Hello World サービスへの参照を受け取ることができます。init() メソッドは、プロパティーインジェクションの後に Bean 初期化フェーズ中に呼び出されます。つまり、通常、このメソッドのスコープ内で Hello World サービスを呼び出すことができます。

12.5.7. クライアントバンドルの実行

osgi-client プロジェクトをインストールおよび実行するには、以下の手順を実行します。

  1. プロジェクトをビルドします - コマンドプロンプトを開き、ProjectDir/osgi-client ディレクトリーに移動します。以下のコマンドを入力して、Maven を使用してデモをビルドします。

    mvn install

    このコマンドが正常に実行されると、ProjectDir/osgi-client/target ディレクトリーにバンドルファイル osgi-client-1.0-SNAPSHOT.jar が含まれるはずです。

  2. osgi-service バンドルのインストールおよび開始 - Red Hat Fuseコンソールで、次のコマンドを入力します。

    karaf@root()> bundle:install -s file:ProjectDir/osgi-client/target/osgi-client-1.0-SNAPSHOT.jar

    ProjectDir は Maven プロジェクトを含むディレクトリーで、-s フラグはバンドルをすぐに起動するように指示します。たとえば、Windows マシンのプロジェクトディレクトリーが C:\Projects の場合、以下のコマンドを入力します。

    karaf@root()> bundle:install -s file:C:/Projects/osgi-client/target/osgi-client-1.0-SNAPSHOT.jar
    注記

    Windowsマシンでは、file URL のフォーマット方法に注意してください。file URLハンドラーが認識する構文の詳細は 「ファイル URL ハンドラー」 を参照してください。

  3. クライアント出力 - クライアントバンドルが正常に起動すると、コンソールで以下のような出力がすぐに表示されるはずです。

    Bundle ID: 239
    OSGi client started.
    Calling sayHello()
    Hello World!

12.6. Apache Camel とのインテグレーション

12.6.1. 概要

Apache Camel は、Bean 言語を使用して OSGi サービスを呼び出す簡単な方法を提供します。この機能は、Apache Camel アプリケーションが OSGi コンテナーにデプロイされるたびに自動的に使用可能になり、特別な設定は必要ありません。

12.6.2. レジストリーチェーン

Apache Camel ルートが OSGi コンテナーにデプロイされると、 CamelContext が Bean インスタンスの解決のためにレジストリーチェーンを自動的に設定します。レジストリーチェーンは OSGi レジストリーとそれに続く Blueprint レジストリーで構成されます。ここで、特定の Bean クラスまたは Bean インスタンスを参照しようとすると、レジストリーは Bean を次のように解決します。

  1. 最初に OSGi レジストリーで Bean を検索します。クラス名が指定されている場合、それを OSGi サービスのインターフェースまたはクラスと一致しようとします。
  2. OSGi レジストリーに一致するものが見つからない場合は、Blueprint レジストリーにフォールバックします。

12.6.3. OSGi サービスインターフェースの例

単一のメソッド getGreeting() を定義する以下の Java インターフェースで定義された OSGi サービスについて考えてみましょう。

package org.fusesource.example.hello.boston;

public interface HelloBoston {
    public String getGreeting();
}

12.6.4. サービスのエクスポート例

HelloBoston OSGi サービスを実装するバンドルを定義するとき、以下の Blueprint 設定を使用してサービスをエクスポートできます。

<?xml version="1.0" encoding="UTF-8"?>
<blueprint xmlns="http://www.osgi.org/xmlns/blueprint/v1.0.0">

  <bean id="hello" class="org.fusesource.example.hello.boston.HelloBostonImpl"/>

  <service ref="hello" interface="org.fusesource.example.hello.boston.HelloBoston"/>

</blueprint>

HelloBoston インターフェースが HelloBostonImpl クラス (ここでは示されていない) によって実装されることを前提とします。

12.6.5. Java DSL からの OSGi サービスの呼び出し

HelloBoston OSGi サービスが含まれるバンドルをデプロイしたら、Java DSL を使用して Apache Camel アプリケーションからサービスを呼び出すことができます。Java DSL では、以下のように Bean 言語を介して OSGi サービスを呼び出します。

from("timer:foo?period=5000")
  .bean(org.fusesource.example.hello.boston.HelloBoston.class, "getGreeting")
  .log("The message contains: ${body}")

bean コマンドでは、最初の引数は OSGi インターフェースまたはクラスで、これは OSGi サービスバンドルからエクスポートされたインターフェースと一致する必要があります。2 つ目の引数は、呼び出す Bean メソッドの名前です。bean コマンド構文の詳細は、『Apache Camel Development Guide』の Bean Integration を参照してください。

注記

この方法を使用すると、OSGi サービスは暗黙的にインポートされます。この場合、OSGiサービスを明示的にインポートする必要はありません

12.6.6. XML DSL からの OSGi サービスの呼び出し

XML DSL では、Bean 言語を使用して HelloBoston OSGi サービスを呼び出すこともできますが、構文は若干異なります。XML DSL では、以下のように method 要素を使用して Bean 言語を介して OSGi サービスを呼び出します。

<beans ...>
  <camelContext xmlns="http://camel.apache.org/schema/spring">
    <route>
      <from uri="timer:foo?period=5000"/>
      <setBody>
          <method ref="org.fusesource.example.hello.boston.HelloBoston" method="getGreeting"/>
      </setBody>
      <log message="The message contains: ${body}"/>
    </route>
  </camelContext>
</beans>
注記

この方法を使用すると、OSGi サービスは暗黙的にインポートされます。この場合、OSGiサービスを明示的にインポートする必要はありません

第13章 JMS ブローカーを使用したデプロイ

概要

Fuse 7.9 にはデフォルトの内部ブローカーが含まれていませんが、4 つの外部 JMS ブローカーとインターフェースするように設計されています。

Fuse 7.9 コンテナーには、サポートされる外部ブローカーのブローカークライアントライブラリーが含まれます。

Fuse 7.9 のメッセージングで使用できる外部ブローカー、クライアント、および Camel コンポーネントの組み合わせに関する詳細は、「Red Hat Fuse でサポートされる構成」を参照してください。

13.1. AMQ 7 クイックスタート

クイックスタートは、AMQ7 ブローカーを使用したアプリケーションのセットアップとデプロイメントを実証するために提供されます。

クイックスタートのダウンロード

Fuse Software Downloads ページからすべてのクイックスタートをインストールできます。

ダウンロードした zip ファイルの内容をローカルフォルダーに展開します (例: quickstarts という名前のフォルダー)。

クイックスタートの設定

  1. quickstarts/camel/camel-jms フォルダーに移動します。
  2. mvn clean install を入力してクイックスタートをビルドします。
  3. org.ops4j.connectionfactory-amq7.cfg ファイルを /camel/camel-jms/src/main ディレクトリーから Fuse インストールの FUSE_HOME/etc ディレクトリーにコピーします。正しいブローカー URLと クレデンシャルの内容を確認します。デフォルトでは、ブローカー URL は AMQ 7 の CORE プロトコルに従って tcp://localhost:61616 に設定されます。クレデンシャルは admin/admin に設定されます。外部ブローカーに合わせてこれらの詳細を変更します。
  4. Linux の場合は ./bin/fuse、Windows の場合は bin\fuse.bat を実行して、Fuse を起動します。
  5. Fuse コンソールで以下のコマンドを入力します。

    feature:install pax-jms-pool artemis-jms-client camel-blueprint camel-jms
    
    install -s mvn:org.jboss.fuse.quickstarts/camel-jms/${project.version}

    バンドルがデプロイされると、Fuse はバンドル ID を提供します。

  6. log:display を入力して、起動ログ情報を表示します。バンドルが正常にデプロイされたことを確認します。
12:13:50.445 INFO [Blueprint Event Dispatcher: 1] Attempting to start Camel Context jms-example-context
12:13:50.446 INFO [Blueprint Event Dispatcher: 1] Apache Camel 2.21.0.fuse-000030 (CamelContext: jms-example-context) is starting
12:13:50.446 INFO [Blueprint Event Dispatcher: 1] JMX is enabled
12:13:50.528 INFO [Blueprint Event Dispatcher: 1] StreamCaching is not in use. If using streams then its recommended to enable stream caching. See more details at http://camel.apache.org/stream-caching.html
12:13:50.553 INFO [Blueprint Event Dispatcher: 1] Route: file-to-jms-route started and consuming from: file://work/jms/input
12:13:50.555 INFO [Blueprint Event Dispatcher: 1] Route: jms-cbr-route started and consuming from: jms://queue:incomingOrders?transacted=true
12:13:50.556 INFO [Blueprint Event Dispatcher: 1] Total 2 routes, of which 2 are started

クイックスタートを実行します。

  1. Camel ルートが実行されると、/camel/camel-jms/work/jms/input ディレクトリーが作成されます。/camel/camel-jms/src/main/data ディレクトリーから /camel/camel-jms/work/jms/input ディレクトリーにファイルをコピーします。
  2. …​/src/main/data ファイルにコピーされたファイルは、順序ファイルです。1 分ほど待ってから、/camel/camel-jms/work/jms/output ディレクトリーを確認します。ファイルは、宛先の国に応じて、個別のディレクトリーに分類されます。

    • /camel/camel-jms/work/jms/output/others/order1.xmlorder2.xml、および order4.xml
    • /camel/camel-jms/work/jms/output/usorder3.xml および order5.xml
    • /camel/camel-jms/work/jms/output/frorder6.xml
  3. log:display を使用してログメッセージを表示します。
Receiving order order1.xml
Sending order order1.xml to another country
Done processing order1.xml
  1. Camel コマンドはコンテキストの詳細を表示します。

camel:context-list を使用してコンテキストの詳細を表示します。

Context               Status              Total #       Failed #     Inflight #   Uptime
-------               ------              -------       --------     ----------   ------
jms-example-context   Started                  12              0              0   3 minutes

camel:route-list を使用して、コンテキストの Camel ルートを表示します。

Context               Route               Status              Total #       Failed #     Inflight #   Uptime
-------               -----               ------              -------       --------     ----------   ------
jms-example-context   file-to-jms-route   Started                   6              0              0   3 minutes
jms-example-context   jms-cbr-route       Started                   6              0              0   3 minutes

camel:route-info を使用してエクスチェンジの統計を表示します。

karaf@root()> camel:route-info jms-cbr-route jms-example-context
Camel Route jms-cbr-route
    Camel Context: jms-example-context
    State: Started
    State: Started

Statistics
    Exchanges Total: 6
    Exchanges Completed: 6
    Exchanges Failed: 0
    Exchanges Inflight: 0
    Min Processing Time: 2 ms
    Max Processing Time: 12 ms
    Mean Processing Time: 4 ms
    Total Processing Time: 29 ms
    Last Processing Time: 4 ms
    Delta Processing Time: 1 ms
    Start Statistics Date: 2018-01-30 12:13:50
    Reset Statistics Date: 2018-01-30 12:13:50
    First Exchange Date: 2018-01-30 12:19:47
    Last Exchange Date: 2018-01-30 12:19:47

13.2. Artemis コアクライアントの使用

Artemis コアクライアントは、qpid-jms-client ではなく外部ブローカーに接続するために使用できます。

Artemis コアクライアントを使用した接続

  1. Artemis コアクライアントを有効にするには Fuse を起動します。FUSE_HOME ディレクトリーに移動し、Linux の場合は ./bin/fuse を入力し、Windows の場合は bin\fuse.bat を入力します。
  2. コマンド feature:install artemis-core-client を使用して、Artemis クライアントを機能として追加します。
  3. コードを作成している場合は、Camel コンポーネントを接続ファクトリーで接続する必要があります。

接続ファクトリーをインポートします。

import org.apache.qpid.jms.JmsConnectionFactory;

接続を設定します。

ConnectionFactory connectionFactory = new JmsConnectionFactory("amqp://localhost:5672");
      try (Connection connection = connectionFactory.createConnection()) {

第14章 デプロイメントのフェイルオーバー

概要

Red Hat Fuse は、簡単なロックファイルシステムまたは JDBC のロッキングメカニズムのいずれかを使用して、フェイルオーバー機能を提供します。いずれの場合も、コンテナーレベルのロックシステムによって、より高速なフェイルオーバーのパフォーマンスを提供するためにバンドルをスレーブカーネルインスタンスに事前ロードできます。

14.1. シンプルなロックファイルシステムの使用

概要

Red Hat Fuse を初めて起動すると、インストールディレクトリーのルートにロックファイルが作成されます。マスターインスタンスに障害が発生した場合に、ロックが同じホストマシンにあるスレーブインスタンスに渡されるようにマスター/スレーブシステムを設定できます。

ロックファイルシステムの設定

ロックファイルのフェイルオーバーデプロイメントを設定するには、マスターおよびスレーブインストール両方の etc/system.properties ファイルを編集し、例14.1「ロックファイルフェイルオーバー設定」 のプロパティーが含まれるようにします。

例14.1 ロックファイルフェイルオーバー設定

karaf.lock=true
karaf.lock.class=org.apache.karaf.main.SimpleFileLock
karaf.lock.dir=PathToLockFileDirectory
karaf.lock.delay=10000
  • karaf.lock はロックファイルが書き込まれるかどうかを指定します。
  • karaf.lock.class は、ロックを実装する Java クラスを指定します。シンプルなファイルロックの場合、常に org.apache.karaf.main.SimpleFileLock である必要があります。
  • karaf.lock.dir は、ロックファイルが書き込まれるディレクトリーを指定します。マスターとスレーブのインストール両方で同じである必要があります
  • karaf.lock.delay は、ロックを再取得する試行間の遅延をミリ秒単位で指定します。

14.2. JDBC ロックシステムの使用

概要

JDBC ロッキングメカニズムは、Red Hat Fuse インスタンスが別のマシンに存在するフェイルオーバーデプロイメントを対象としています。

このシナリオでは、マスターインスタンスはデータベースでホストされるロッキングテーブルのロックを保持します。マスターでロックが失われた場合、待機しているスレーブプロセスがロックテーブルにアクセスできるようになり、そのコンテナーを完全に起動します。

JDBC ドライバーのクラスパスへの追加

JDBC ロッキングシステムでは、JDBC ドライバーは、マスター/スレーブセットアップの各インスタンスのクラスパス上にある必要があります。以下のように JDBC ドライバーをクラスパスに追加します。

  1. JDBC ドライバー JAR ファイルを各 Red Hat Fuse インスタンスの ESBInstallDir/lib/ext ディレクトリーにコピーします。
  2. bin/karaf 変数に JDBC ドライバー JAR が含まれるように CLASSPATH 起動スクリプトを変更します。

    たとえば、JDBC JAR ファイル JDBCJarFile.jar の場合、以下のように起動スクリプトを変更できます (*NIX オペレーティングシステムの場合)。

        ...
        # Add the jars in the lib dir
        for file in "$KARAF_HOME"/lib/karaf*.jar
        do
            if [ -z "$CLASSPATH" ]; then
                CLASSPATH="$file"
            else
                CLASSPATH="$CLASSPATH:$file"
            fi
        done
        CLASSPATH="$CLASSPATH:$KARAF_HOME/lib/JDBCJarFile.jar"
    注記

    MySQL ドライバー JAR または PostgreSQL ドライバー JAR を追加する場合、karaf- プレフィックスを付けてドライバー JAR の名前を変更する必要があります。それ以外の場合は、Apache Karaf がハングし、ドライバーが見つからなかったことがログに記録されます。

JDBC ロックシステムの設定

JDBC ロックシステムを設定するには、以下のようにマスター/スレーブデプロイメント内の各インスタンスの etc/system.properties ファイルを更新します。

例14.2 JDBC ロックファイルの設定

karaf.lock=true
karaf.lock.class=org.apache.karaf.main.lock.DefaultJDBCLock
karaf.lock.level=50
karaf.lock.delay=10000
karaf.lock.jdbc.url=jdbc:derby://dbserver:1527/sample
karaf.lock.jdbc.driver=org.apache.derby.jdbc.ClientDriver
karaf.lock.jdbc.user=user
karaf.lock.jdbc.password=password
karaf.lock.jdbc.table=KARAF_LOCK
karaf.lock.jdbc.clustername=karaf
karaf.lock.jdbc.timeout=30

この例では、sample という名前のデータベースが存在しない場合はそれが作成されます。ロックテーブルを取得する最初の Red Hat Fuse インスタンスはマスターインスタンスです。データベースへの接続が失われた場合、マスターインスタンスは正常なシャットダウンを試行し、データベースサービスが復元する際にスレーブインスタンスをマスターにすることができます。以前のマスターは手動で再起動する必要があります。

Oracle での JDBC ロッキングの設定

JDBC ロッキングのシナリオで Oracle をデータベースとして使用している場合は、etc/system.properties ファイルの karaf.lock.class プロパティーが org.apache.karaf.main.lock.OracleJDBCLock を示す必要があります。

それ以外の場合は、以下に示すように、設定に system.properties ファイルを通常どおりに設定します。

例14.3 Oracle の JDBC ロックファイルの設定

karaf.lock=true
karaf.lock.class=org.apache.karaf.main.lock.OracleJDBCLock
karaf.lock.jdbc.url=jdbc:oracle:thin:@hostname:1521:XE
karaf.lock.jdbc.driver=oracle.jdbc.OracleDriver
karaf.lock.jdbc.user=user
karaf.lock.jdbc.password=password
karaf.lock.jdbc.table=KARAF_LOCK
karaf.lock.jdbc.clustername=karaf
karaf.lock.jdbc.timeout=30
注記

karaf.lock.jdbc.url には、アクティブな Oracle システム ID (SID) が必要です。これは、この特定のロックを使用する前に、データベースインスタンスを手動で作成する必要があります。

Derby での JDBC ロッキングの設定

JDBC ロッキングのシナリオで Derby をデータベースとして使用している場合は、etc/system.properties ファイルの karaf.lock.class プロパティーが org.apache.karaf.main.lock.DerbyJDBCLock を示す必要があります。たとえば、以下のように system.properties ファイルを設定できます。

例14.4 Derby の JDBC ロックファイルの設定

karaf.lock=true
karaf.lock.class=org.apache.karaf.main.lock.DerbyJDBCLock
karaf.lock.jdbc.url=jdbc:derby://127.0.0.1:1527/dbname
karaf.lock.jdbc.driver=org.apache.derby.jdbc.ClientDriver
karaf.lock.jdbc.user=user
karaf.lock.jdbc.password=password
karaf.lock.jdbc.table=KARAF_LOCK
karaf.lock.jdbc.clustername=karaf
karaf.lock.jdbc.timeout=30

MySQL での JDBC ロッキングの設定

JDBC ロッキングのシナリオで MySQL をデータベースとして使用している場合は、etc/system.properties ファイルの karaf.lock.class プロパティーが org.apache.karaf.main.lock.MySQLJDBCLock を示す必要があります。たとえば、以下のように system.properties ファイルを設定できます。

例14.5 MySQL の JDBC ロックファイルの設定

karaf.lock=true
karaf.lock.class=org.apache.karaf.main.lock.MySQLJDBCLock
karaf.lock.jdbc.url=jdbc:mysql://127.0.0.1:3306/dbname
karaf.lock.jdbc.driver=com.mysql.jdbc.Driver
karaf.lock.jdbc.user=user
karaf.lock.jdbc.password=password
karaf.lock.jdbc.table=KARAF_LOCK
karaf.lock.jdbc.clustername=karaf
karaf.lock.jdbc.timeout=30

PostgreSQL での JDBC ロッキングの設定

JDBC ロッキングのシナリオで PostgreSQL をデータベースとして使用している場合は、etc/system.properties ファイルの karaf.lock.class プロパティーが org.apache.karaf.main.lock.PostgreSQLJDBCLock を示す必要があります。たとえば、以下のように system.properties ファイルを設定できます。

例14.6 PostgreSQL の JDBC ロックファイルの設定

karaf.lock=true
karaf.lock.class=org.apache.karaf.main.lock.PostgreSQLJDBCLock
karaf.lock.jdbc.url=jdbc:postgresql://127.0.0.1:5432/dbname
karaf.lock.jdbc.driver=org.postgresql.Driver
karaf.lock.jdbc.user=user
karaf.lock.jdbc.password=password
karaf.lock.jdbc.table=KARAF_LOCK
karaf.lock.jdbc.clustername=karaf
karaf.lock.jdbc.timeout=0

JDBC ロッククラス

現在、以下の JDBC ロッククラスが Apache Karaf によって提供されます。

org.apache.karaf.main.lock.DefaultJDBCLock
org.apache.karaf.main.lock.DerbyJDBCLock
org.apache.karaf.main.lock.MySQLJDBCLock
org.apache.karaf.main.lock.OracleJDBCLock
org.apache.karaf.main.lock.PostgreSQLJDBCLock

14.3. コンテナーレベルのロッキング

概要

コンテナーレベルのロッキングによって、より高速なフェイルオーバーのパフォーマンスを提供するためにバンドルをスレーブカーネルインスタンスに事前ロードできます。コンテナーレベルのロッキングは、シンプルなファイルおよび JDBC ロッキングメカニズムの両方でサポートされます。

コンテナーレベルのロッキングの設定

コンテナーレベルのロッキングを実装するには、マスター/スレーブ設定の各システムの etc/system.properties ファイルに以下を追加します。

例14.7 コンテナーレベルのロッキングの設定

karaf.lock=true
karaf.lock.level=50
karaf.lock.delay=10000

karaf.lock.level プロパティーでは、Red Hat Fuse インスタンスが OSGi コンテナーを起動するために起動プロセスをどこまで実行するかを示します。同じ開始レベル以下が割り当てられたバンドルも、その Fuse インスタンスで開始されます。

バンドル開始レベルは、BundleName.jar=level の形式で etc/startup.properties に指定されます。コアシステムバンドルのレベルは 50 未満ですが、ユーザーバンドルのレベルは 50 を超えます。

表14.1 Bundle 開始レベル

開始レベル動作

1

「コールド」スタンバイインスタンス。コアバンドルはコンテナーにロードされません。スレーブは、ロックが取得されるまで待ち、サーバーを開始します。

<50

「ホット」スタンバイインスタンス。コアバンドルはコンテナーにロードされます。スレーブは、ロックが取得されるまで待ち、ユーザーレベルバンドルを開始します。コンソールは、このレベルで各スレーブインスタンスに対してアクセス可能です。

>50

ユーザーバンドルが開始されるため、この設定は推奨されません。

ポート競合の回避

同じホストで「ホット」スペアを使用する場合は、バインドの競合を避けるために、JMX リモートポートを一意の値に設定する必要があります。fuse 起動スクリプト (または子インスタンス上の karaf スクリプト) を編集して、以下が含まれるようにすることができます。

DEFAULT_JAVA_OPTS="-server $DEFAULT_JAVA_OPTS -Dcom.sun.management.jmxremote.port=1100 -Dcom.sun.management.jmxremote.authenticate=false"

第15章 URL ハンドラー

Red Hat Fuse には、リソースの場所を指定する URL を提供する必要がある多くのコンテキストがあります (たとえば、コンソールコマンドへの引数として) 。通常、URL を指定する場合、Fuse のビルトイン URL ハンドラーによってサポートされるスキームのいずれかを使用できます。この付録では、利用可能なすべての URL ハンドラーの構文を説明します。

15.1. ファイル URL ハンドラー

15.1.1. 構文

ファイル URL の構文は file:PathName で、PathName は、Classpath で利用可能なファイルの相対パスまたは絶対パス名です。提供された PathName は、Java の組み込みファイル URL ハンドラー によって解析されます。そのため、PathName 構文は Java パス名の通常の規則に従います。特に Windows では、各バックスラッシュを別のバックスラッシュでエスケープするか、スラッシュに置き換える必要があります。

15.1.2. 例

たとえば、Windows におけるパス名 C:\Projects\camel-bundle\target\foo-1.0-SNAPSHOT.jar について考えてみましょう。以下の例は、Windows でのファイル URL の正しい代替手段を示しています。

file:C:/Projects/camel-bundle/target/foo-1.0-SNAPSHOT.jar
file:C:\\Projects\\camel-bundle\\target\\foo-1.0-SNAPSHOT.jar

以下の例は、Windows でのファイル URL の正しくない代替手段を示しています。

file:C:\Projects\camel-bundle\target\foo-1.0-SNAPSHOT.jar        // WRONG!
file://C:/Projects/camel-bundle/target/foo-1.0-SNAPSHOT.jar      // WRONG!
file://C:\\Projects\\camel-bundle\\target\\foo-1.0-SNAPSHOT.jar  // WRONG!

15.2. HTTP URL ハンドラー

15.2.1. 構文

HTTP URL には標準の構文 http:Host[:Port]/[Path][#AnchorName][?Query] があります。https スキームを使用してセキュアな HTTP URL を指定することもできます。提供される HTTP URL は Java のビルトイン HTTP URL ハンドラーによって解析されるため、HTTP URL は Java アプリケーションに対して通常どおりに動作します。

15.3. Mvn URL ハンドラー

15.3.1. 概要

Maven を使用してバンドルをビルドする場合や、特定のバンドルを Maven リポジトリーから利用できることを知っている場合は、Mvn ハンドラースキームを使用してバンドルを見つけることができます。

注記

Mvn URL ハンドラーがローカルおよびリモートの Maven アーティファクトを見つけるようにするには、Mvn URL ハンドラーの設定をカスタマイズする必要がある場合があります。詳細は、「Mvn URL ハンドラーの設定」 を参照してください。

15.3.2. 構文

Mvn URL の構文は以下のとおりです。

mvn:[repositoryUrl!]groupId/artifactId[/[version][/[packaging][/[classifier]]]]

repositoryUrl は、必要に応じて Maven リポジトリーの URL を指定します。groupIdartifactIdversionpackages、および classifier は、Maven アーティファクトを見つけるための標準の Maven コーディネートです。

15.3.3. コーディネートの省略

Mvn URL を指定する場合には、groupIdartifactId コーディネートのみが必要になります。以下は、groupIdorg.fusesource.exampleartifactIdbundle-demo で Maven バンドルを参照する例です。

mvn:org.fusesource.example/bundle-demo
mvn:org.fusesource.example/bundle-demo/1.1

最初の例のように、バージョンを省略すると、デフォルトは LATEST に設定されます。これにより、利用可能な Maven メタデータに基づいて最新バージョンに解決されます。

packaging または version の値を指定せずに classifier の値を指定するために、Mvn URL でそれらの値を未指定にすることができます。version の値を指定せずに packaging の値を指定する場合も同じです。以下に例を示します。

mvn:groupId/artifactId///classifier
mvn:groupId/artifactId/version//classifier
mvn:groupId/artifactId//packaging/classifier
mvn:groupId/artifactId//packaging

15.3.4. バージョン範囲の指定

Mvn URL で version の値を指定する場合は、バージョン番号の代わりにバージョンの範囲 (標準の Maven バージョン範囲の構文を使用) を指定できます。角括弧 [ および ] を使用して含まれる範囲を示し、括弧 ( および ) を使用して除外される範囲を示します。たとえば、範囲 [1.0.4,2.0) は、1.0.4 ⇐ v < 2.0 を満たすすべてのバージョン v に一致します。以下のように Mvn URL でこのバージョン範囲を使用できます。

mvn:org.fusesource.example/bundle-demo/[1.0.4,2.0)

15.3.5. Mvn URL ハンドラーの設定

Mvn URL を初めて使用する前に、以下のように Mvn URL ハンドラーの設定をカスタマイズする必要がある場合があります。

15.3.6. Mvn URL 設定の確認

Mvn URL ハンドラーは、ローカルの Maven リポジトリーへの参照を解決し、リモート Maven リポジトリーのリストを維持します。Mvn URL を解決するとき、ハンドラーは最初にローカルリポジトリーを検索し、その後にリモートリポジトリーを検索して、指定された Maven アーティファクトを特定します。Mvn URL の解決に問題がある場合は、最初に、ハンドラー設定をチェックして、URL の解決に使用するローカルリポジトリーとリモートリポジトリーを確認する必要があります。

Mvn URL 設定を確認するには、コンソールで以下のコマンドを入力します。

JBossFuse:karaf@root> config:edit org.ops4j.pax.url.mvn
JBossFuse:karaf@root> config:proplist

config:edit コマンドは、config ユーティリティーの焦点を org.ops4j.pax.url.mvn 永続 ID に属するプロパティーに切り替えます。config:proplist コマンドは、現在の永続 ID のプロパティー設定をすべて出力します。org.ops4j.pax.url.mvn を対象とすると、以下のようなリストが表示されるはずです。

   org.ops4j.pax.url.mvn.defaultRepositories = file:/path/to/JBossFuse/jboss-fuse-7.9.0.fuse-790071-redhat-00001/system@snapshots@id=karaf.system,file:/home/userid/.m2/repository@snapshots@id=local,file:/path/to/JBossFuse/jboss-fuse-7.9.0.fuse-790071-redhat-00001/local-repo@snapshots@id=karaf.local-repo,file:/path/to/JBossFuse/jboss-fuse-7.9.0.fuse-790071-redhat-00001/system@snapshots@id=child.karaf.system
   org.ops4j.pax.url.mvn.globalChecksumPolicy = warn
   org.ops4j.pax.url.mvn.globalUpdatePolicy = daily
   org.ops4j.pax.url.mvn.localRepository = /path/to/JBossFuse/jboss-fuse-7.9.0.fuse-790071-redhat-00001/data/repository
   org.ops4j.pax.url.mvn.repositories = http://repo1.maven.org/maven2@id=maven.central.repo, https://maven.repository.redhat.com/ga@id=redhat.ga.repo, https://maven.repository.redhat.com/earlyaccess/all@id=redhat.ea.repo, https://repository.jboss.org/nexus/content/groups/ea@id=fuseearlyaccess
   org.ops4j.pax.url.mvn.settings = /path/to/jboss-fuse-7.9.0.fuse-790071-redhat-00001/etc/maven-settings.xml
   org.ops4j.pax.url.mvn.useFallbackRepositories = false
   service.pid = org.ops4j.pax.url.mvn

localRepository 設定は、ハンドラーによって現在使用されているローカルリポジトリーの場所を示し、repositories の設定は、ハンドラーによって現在使用されているリモートリポジトリーのリストを示します。

15.3.7. 設定ファイルの編集

Mvn URL ハンドラーのプロパティー設定をカスタマイズするには、以下の設定ファイルを編集します。

InstallDir/etc/org.ops4j.pax.url.mvn.cfg

このファイルの設定により、ローカル Maven リポジトリーの場所を明示的に指定したり、Maven リポジトリーや Maven プロキシーサーバー設定などを削除したりできます。これらの設定の詳細については、設定ファイルのコメントを参照してください。

15.3.8. ローカルリポジトリーの場所のカスタマイズ

特に、ローカルの Maven リポジトリーがデフォルト以外の場所にある場合は、ローカルでビルドした Maven アーティファクトにアクセスするために明示的に設定する必要がある場合があります。org.ops4j.pax.url.mvn.cfg 設定ファイルで、org.ops4j.pax.url.mvn.localRepository プロパティーのコメントを解除して、ローカルの Maven リポジトリーの場所に設定します。以下に例を示します。

# Path to the local maven repository which is used to avoid downloading
# artifacts when they already exist locally.
# The value of this property will be extracted from the settings.xml file
# above, or defaulted to:
#     System.getProperty( "user.home" ) + "/.m2/repository"
#
org.ops4j.pax.url.mvn.localRepository=file:E:/Data/.m2/repository

15.3.9. リファレンス

mvn URL 構文の詳細は、元の Pax URL の Mvn Protocol ドキュメントを参照してください。

15.4. Wrap URL ハンドラー

15.4.1. 概要

バンドルとしてパッケージ化されていない JAR ファイルを参照する必要がある場合は、Wrap URL ハンドラーを使用して動的に変換できます。Wrap URL ハンドラーの実装は、Peter Krien 氏のオープンソース Bnd ユーティリティーに基づいています。

15.4.2. 構文

Wrap URL の構文は以下のとおりです。

wrap:locationURL[,instructionsURL][$instructions]

locationURL は、JAR を検索する URL にすることができます (参照される JAR はバンドルとしてフォーマットされません) 。任意の instructionsURL は、バンドル変換の実行方法を指定する Bnd プロパティーファイルを参照します。任意の instructions は、バンドル変換の実行方法を指定する、アンパサンド & で区切られた Bnd プロパティーのリストです。

15.4.3. デフォルトの命令

ほとんどの場合、API JAR ファイルをラップするには、デフォルトの Bnd 命令で十分です。デフォルトでは、Wrap は、表15.1「JAR をラップするためのデフォルトの命令」 に示されているようにマニフェストヘッダーを JAR の META-INF/Manifest.mf ファイルに追加します。

表15.1 JAR をラップするためのデフォルトの命令

マニフェストヘッダーデフォルト値

Import-Package

*;resolution:=optional

Export-Package

ラップされた JAR からのすべてのパッケージ。

Bundle-SymbolicName

JAR ファイルの名前。セット [a-zA-Z0-9_-] にない文字はすべてアンダースコア _ に置き換えられます。

15.4.4. 例

以下の Wrap URL は、Maven リポジトリーでバージョン 1.1 の commons-logging JAR のを見つけ、デフォルトの Bnd プロパティーを使用してこれを OSGi バンドルに変換します。

wrap:mvn:commons-logging/commons-logging/1.1

以下の Wrap URL は、ファイル E:\Data\Examples\commons-logging-1.1.bnd からの Bnd プロパティーを使用します。

wrap:mvn:commons-logging/commons-logging/1.1,file:E:/Data/Examples/commons-logging-1.1.bnd

以下の Wrap URL は、Bundle-SymbolicName プロパティーと Bundle-Version プロパティーを明示的に指定します。

wrap:mvn:commons-logging/commons-logging/1.1$Bundle-SymbolicName=apache-comm-log&Bundle-Version=1.1

上記の URL をコマンドライン引数として使用する場合は、以下のようにドル記号を \$ のようにエスケープしてコマンドラインで処理されないようにする必要がある場合があります。

wrap:mvn:commons-logging/commons-logging/1.1\$Bundle-SymbolicName=apache-comm-log&Bundle-Version=1.1

15.4.5. リファレンス

wrap URL ハンドラーの詳細は、以下の参考資料を参照してください。

15.5. War URL ハンドラー

15.5.1. 概要

OSGi コンテナーに WAR ファイルをデプロイする必要がある場合は、ここで説明するように war: を WAR URL の先頭に追加し、必要なマニフェストヘッダーを WAR ファイルに自動的に追加できます。

15.5.2. 構文

War URL は、以下の構文のいずれかを使用して指定されます。

war:warURL
warref:instructionsURL

war スキームを使用する最初の構文は、デフォルトの命令を使用してバンドルに変換される WAR ファイルを指定します。warURL は、WAR ファイルを見つける任意の URL です。

warref スキームを使用する 2 番目の構文は、変換命令 (このハンドラーに固有の命令を含む) が含まれる Bnd プロパティーファイル instructionsURL を指定します。この構文では、参照された WAR ファイルの場所は URL に明示的に示されません。代わりに、WAR ファイルは、プロパティーファイルの (必須の) WAR-URL プロパティーにより指定されます。

15.5.3. WAR 固有のプロパティー/命令

以下のように、.bnd 命令ファイルのプロパティーの一部は、War URL ハンドラーに固有です。

WAR-URL
(必須) バンドルに変換される War ファイルの場所を指定します。
Web-ContextPath

Web コンテナー内にデプロイされた後に、この Web アプリケーションへのアクセスに使用される URL パスの一部を指定します。

注記

PAX Web の以前のバージョンでは、現在非推奨となっているプロパティー Webapp-Context が使用されていました。

15.5.4. デフォルトの命令

デフォルトでは、表15.2「WAR ファイルをラップするためのデフォルトの命令」 に示すように、War URL ハンドラーは WAR の META-INF/Manifest.mf ファイルにマニフェストヘッダーを追加します。

表15.2 WAR ファイルをラップするためのデフォルトの命令

マニフェストヘッダーデフォルト値

Import-Package

javax.,org.xml.,org.w3c.*

Export-Package

パッケージはエクスポートされません。

Bundle-SymbolicName

WAR ファイルの名前。セット [a-zA-Z0-9_-\.] にない文字はすべてピリオド . に置き換えられます。

Web-ContextPath

デフォルト値なし。しかし、WAR エクステンダーは、デフォルトで Bundle-SymbolicName の値を使用します。

Bundle-ClassPath

明示的に指定されたクラスパスエントリーの他に、以下のエントリーが自動的に追加されます。

  • .
  • WEB-INF/classes
  • WEB-INF/lib ディレクトリーからのすべての JAR。

15.5.5. 例

以下の War URL は、Maven リポジトリーの wicket-examples WAR のバージョン 1.4.7 を見つけ、これをデフォルトの命令を使用して OSGi バンドルに変換します。

war:mvn:org.apache.wicket/wicket-examples/1.4.7/war

以下の Wrap URL は、Web-ContextPath を明示的に指定します。

war:mvn:org.apache.wicket/wicket-examples/1.4.7/war?Web-ContextPath=wicket

以下の War URL は、wicket-examples-1.4.7.bnd ファイルの WAR-URL プロパティーによって参照される WAR ファイルを変換し、.bnd ファイルの他の命令を使用して WAR を OSGi バンドルに変換します。

warref:file:E:/Data/Examples/wicket-examples-1.4.7.bnd

15.5.6. リファレンス

war URL 構文の詳細は、元の Pax URL の War Protocol ドキュメントを参照してください。

パート II. ユーザーガイド

このパートには、Apache Karaf on Red Hat Fuse の設定および準備情報が含まれます。

第16章 『Apache Karaf へのデプロイ』ユーザーガイド

概要

『Apache Karaf のデプロイ』のユーザーガイドセクションを使用する前に、セクションを使用する前に、『Installing on Apache Karaf』の手順にしたがって、最新バージョンの Red Hat Fuse をインストールしておく必要があります。

16.1. Fuse 設定の概要

OSGi Configuration Admin サービスは、デプロイされたサービスの設定情報を指定し、アクティブな場合にサービスがそのデータを受信するようにします。

16.2. OSGi の設定

設定は、FUSE_HOME/etc ディレクトリーの .cfg ファイルから読み取られた名前と値のペアのリストです。ファイルは、Java プロパティーファイル形式を使用して解釈されます。ファイル名は、設定されるサービスの永続識別子 (PID) にマッピングされます。OSGi では、コンテナーの再起動時にサービスを特定するために PID が使用されます。

16.3. 設定ファイル

以下のファイルを使用して、Red Hat Fuse ランタイムを設定できます。

表16.1 Fuse 設定ファイル

ファイル名説明

config.properties

コンテナーの主な設定ファイル。

custom.properties

コンテナーのカスタムプロパティーの主な設定ファイル。

keys.properties

SSH キーベースのプロトコルを使用して Fuse ランタイムにアクセスできるユーザーをリストします。ファイルの内容の形式は username=publicKey,role です。

org.apache.karaf.features.repos.cfg

features リポジトリーの URL。

org.apache.karaf.features.cfg

Fuse を初めて起動したときに、登録する features リポジトリーのリストとインストールする機能のリストを設定します。

org.apache.karaf.jaas.cfg

Karaf JAAS ログインモジュールのオプションを設定します。主に暗号化パスワードの設定に使用されます (デフォルトでは無効) 。

org.apache.karaf.log.cfg

log コンソールコマンドの出力を設定します。

org.apache.karaf.management.cfg

JMX システムを設定します。

org.apache.karaf.shell.cfg

リモートコンソールのプロパティーを設定します。

org.ops4j.pax.logging.cfg

ロギングシステムを設定します。

org.ops4j.pax.transx.tm.narayana.cfg

Narayana トランザクションマネージャーの設定

org.ops4j.pax.url.mvn.cfg

追加の URL リゾルバーを設定します。

org.ops4j.pax.web.cfg

デフォルトの Undertow コンテナー (Web サーバー) を設定します。『Red Hat Fuse Apache CXF Security Guide』の「Securing the Undertow HTTP Server」を参照してください。

startup.properties

コンテナーで起動するバンドルと、その開始レベルを指定します。エントリーは bundle=start-level の形式を取ります。

system.properties

Java システムプロパティーを指定します。このファイルで設定されているプロパティーは、System.getProperties() を使用して起動時に利用できます。

users.properties

リモートまたは Web コンソールを介して Fuse ランタイムにアクセスできるユーザーを一覧表示します。ファイルの内容は username=password,role の形式を取ります。

setenv または setenv.bat

このファイルは、/bin ディレクトリーにあります。JVM オプションの設定に使用されます。ファイルの内容は JAVA_MIN_MEM=512M の形式を取ります。512M は Java メモリーの最小サイズです。詳細は、「Java オプションの設定」 を参照してください。

16.4. 高度な Undertow 設定

16.4.1. IO の設定

PAXWEB-1255 以降、リスナーによって使用される XNIO ワーカーおよびバッファープールの設定を変更できます。undertow.xml テンプレートには、一部の IO 関連のパラメーターのデフォルト値を指定するセクションがあります。

<!-- Only "default" worker and buffer-pool are supported and can be used to override the default values used by all listeners
    buffer-pool:
     - buffer-size defaults to:
        - when < 64MB of Xmx: 512
        - when < 128MB of Xmx: 1024
        - when >= 128MB of Xmx: 16K - 20
     - direct-buffers defaults to:
        - when < 64MB of Xmx: false
        - when >= 64MB of Xmx: true
    worker:
     - io-threads defaults to Math.max(Runtime.getRuntime().availableProcessors(), 2);
     - task-core-threads and task-max-threads default to io-threads * 8
-->

<!--
<subsystem xmlns="urn:jboss:domain:io:3.0">
    <buffer-pool name="default" buffer-size="16364" direct-buffers="true" />
    <worker name="default" io-threads="8" task-core-threads="64" task-max-threads="64" task-keepalive="60000" />
</subsystem>
-->

以下の buffer-pool パラメーターを指定できます。

buffer-size
IO 操作に使用されるバッファーのサイズを指定します。指定のない場合は、利用可能なメモリーに応じてサイズが計算されます。
direct-buffers
java.nio.ByteBuffer#allocateDirect または java.nio.ByteBuffer#allocate を使用するかどうかを決定します。

以下の worker パラメーターを指定できます。

io-threads
ワーカー用に作成する I/O スレッドの数。指定のない場合は、スレッド数は CPU の数の 2 倍に設定されます。
task-core-threads
コアタスクスレッドプールのスレッド数。
task-max-threads
ワーカータスクスレッドプールの最大スレッド数。指定のない場合は、最大スレッド数は CPU の数の 16 倍に設定されます。

16.4.2. ワーカー IO 設定

Undertow スレッドプールおよびその名前は、サービスごとまたはバンドルベースで設定できます。これは、Hawtio コンソールから監視し、より効率的にデバッグするのに役立ちます。

バンドル Blueprint 設定ファイル (通常は Maven プロジェクトの src/main/resources/OSGI-INF/blueprint ディレクトリーに保存される) では、以下の例のように workerIOName および ThreadPool を設定できます。

例16.1 workerIOName および ThreadPool 設定の httpu:engine-factory 要素

<httpu:engine-factory>
    <httpu:engine port="9001">
        <httpu:threadingParameters minThreads="99" maxThreads="777" workerIOThreads="8" workerIOName="WorkerIOTest"/>
    </httpu:engine>
</httpu:engine-factory>

以下の threadingParameters を指定できます。

minThreads
ワーカータスクスレッドプールの「コア」スレッドの数を指定します。通常、これは適度に高く、CPU コアあたり少なくとも 10 である必要があります。
maxThreads
ワーカータスクスレッドプールの最大スレッド数を指定します。

以下の worker パラメーターを指定できます。

workerIOThreads
ワーカーに作成する I/O スレッドの数を指定します。指定されていない場合、デフォルトが選択されます。デフォルト値が CPU コアごとに 1 つの IO スレッドであれば妥当です。
workerIOName
ワーカーの名前を指定します。指定しないと、デフォルトの「XNIO-1」が選択されます。

16.5. 設定ファイルの命名規則

設定ファイルの命名規則は、設定が OSGi Managed Service または OSGi Managed Service ファクトリーであるかどうかによって異なります。

OSGi Managed Service の設定ファイルは、以下の命名規則に従います。

<PID>.cfg

<PID> は、OSGi Managed Service の永続 ID です (OSGi Configuration Admin 仕様で定義されます)。永続 ID は通常、org.ops4j.pax.web のようにドットで区切られています。

OSGi Managed Service Factory の設定ファイルは、以下の命名規則に従います。

<PID>-<InstanceID>.cfg

<PID> は、OSGi Managed Service Factory の 永続 ID です。マネージドサービスファクトリーの <PID>, の場合、ハイフンの後に任意のインスタンス ID <InstanceID> を追加できます。次に、マネージドサービスファクトリーは、見つかった <InstanceID> ごとに一意のサービスインスタンスを作成します。

16.6. Java オプションの設定

Java Options は、Linux の /bin/setenv ファイルまたは Windows の bin/setenv.bat ファイルを使用して設定できます。このファイルを使用して Java オプションのグループを直接設定します (JAVA_MIN_MEM、JAVA_MAX_MEM、JAVA_PERM_MEM、JAVA_MAX_PERM_MEM) 。他の Java オプションは、EXTRA_JAVA_OPTS 変数を使用して設定できます。

たとえば、JVM の最小メモリーを割り当てる場合は以下を使用します。

JAVA_MIN_MEM=512M # Minimum memory for the JVM
To set a Java option other than the direct options, use
EXTRA_JAVA_OPTS="Java option"
For example,
EXTRA_JAVA_OPTS="-XX:+UseG1GC"

16.7. 設定コンソールコマンド

Fuse 7.9 の設定を変更または問い合わせするために使用できるコンソールコマンドが複数あります。

config: コマンドの詳細は、『Apache Karaf Console Reference』の 「Config」セクションを参照してください。

16.8. JMX ConfigMBean

JMX レイヤーでは、MBean は設定管理専用です。

ConfigMBean オブジェクト名は org.apache.karaf:type=config,name=*` です。

14.1.2.1.属性

設定 MBean にはすべての設定 PID の一覧が含まれます。

14.1.2.2.操作

表16.2 JMX MBean 操作

操作名説明

listProperties(pid)

設定 pid のプロパティーのリスト (property=value formatted) を返します。

deleteProperty(pid, property)

設定 pid からプロパティーを削除します。

appendProperty(pid, property, value)

設定 pid のプロパティー値の最後に値を追加します。

setProperty(pid, property, value)

設定 pid のプロパティーに値を設定します。

delete(pid)

pid によって識別される設定を削除します。

create(pid)

pid を使用して、空 (プロパティーなし) の設定を作成します。

update(pid, properties)

提供されたプロパティーマップで pid で識別される設定を更新します。

16.9. コンソールの使用

16.9.1. 利用可能なコマンド

コンソールで利用可能なコマンドを一覧表示するには、help を使用できます。

karaf@root()> help
bundle                            Enter the subshell
bundle:capabilities               Displays OSGi capabilities of a given bundles.
bundle:classes                    Displays a list of classes/resources contained in the bundle
bundle:diag                       Displays diagnostic information why a bundle is not Active
bundle:dynamic-import             Enables/disables dynamic-import for a given bundle.
bundle:find-class                 Locates a specified class in any deployed bundle
bundle:headers                    Displays OSGi headers of a given bundles.
bundle:id                         Gets the bundle ID.
...

簡単な説明を含むすべてのコマンドのリストがあります。

Tab キーを使用すると、すべてのコマンドのクイックリストを取得できます。

karaf@root()> Display all 294 possibilities? (y or n)
...

16.9.2. サブシェルおよび補完モード

コマンドにはスコープと名前があります。たとえば、コマンド feature:list のスコープは feature で、名前は list です。

Karaf はコマンドをスコープによって「グループ化」します。各スコープはサブシェルを形成します。

完全修飾名 (scope:name) でコマンドを直接実行できます。

karaf@root()> feature:list
...

または、サブシェルに入り、コンテキストなコマンドを入力します。

karaf@root()> feature
karaf@root(feature)> list

サブシェル名 (ここでは feature) を入力して、サブシェルに直接入力できることに注意してください。サブシェルから別のサブシェルに直接「切り替える」ことができます。

karaf@root()> feature
karaf@root(feature)> bundle
karaf@root(bundle)>

プロンプトでは () の間に現在のサブシェルが表示されます。

exit コマンドは、親サブシェルに対して実行されます。

karaf@root()> feature
karaf@root(feature)> exit
karaf@root()>

補完モードは、Tab キーおよび help コマンドの動作を定義します。

利用可能なモードは 3 つあります。

  • GLOBAL
  • FIRST
  • SUBSHELL

etc/org.apache.karaf.shell.cfg ファイルの completionMode プロパティーを使用して、デフォルトの補完モードを定義できます。デフォルトでは、以下があります。

completionMode = GLOBAL

shell:completion コマンドを使用して、(Karaf シェルコンソールの使用中に) 補完モードを即座に変更することもできます。

karaf@root()> shell:completion
GLOBAL
karaf@root()> shell:completion FIRST
karaf@root()> shell:completion
FIRST

shell:completion は現在使用されている補完モードについて通知できます。また、必要な新しい補完モードを提供することもできます。

GLOBAL 補完モードは、Karaf 4.0.0 のデフォルトモードです (主に遷移用) 。

GLOBAL モードは実際にはサブシェルを使用しません。以前のバージョンの Karaf と同じ動作です。

tab キーを入力すると、どのサブシェルでも、すべてのコマンドとすべてのエイリアスが表示されます。

karaf@root()> <TAB>
karaf@root()> Display all 273 possibilities? (y or n)
...
karaf@root()> feature
karaf@root(feature)> <TAB>
karaf@root(feature)> Display all 273 possibilities? (y or n)

FIRST 補完モードは GLOBAL 補完モードに代わるものです。

ルートレベルのサブシェルで Tab キーを入力すると、すべてのサブシェルからコマンドとエイリアスが表示されます (GLOBAL モードのように)。ただし、サブシェルにいる場合に Tab キーを入力すると、補完では現在のサブシェルのコマンドのみが表示されます。

karaf@root()> shell:completion FIRST
karaf@root()> <TAB>
karaf@root()> Display all 273 possibilities? (y or n)
...
karaf@root()> feature
karaf@root(feature)> <TAB>
karaf@root(feature)>
info install list repo-add repo-list repo-remove uninstall version-list
karaf@root(feature)> exit
karaf@root()> log
karaf@root(log)> <TAB>
karaf@root(log)>
clear display exception-display get log set tail

SUBSHELL 補完モードは、実際のサブシェルモードです。

ルートレベルで Tab キーを入力すると、サブシェルコマンド (サブシェルに移動する) とグローバルエイリアスが表示されます。サブシェルに入り、Tab キーを入力すると、補完では現在のサブシェルのコマンドが表示されます。

karaf@root()> shell:completion SUBSHELL
karaf@root()> <TAB>
karaf@root()>
* bundle cl config dev feature help instance jaas kar la ld lde log log:list man package region service shell ssh system
karaf@root()> bundle
karaf@root(bundle)> <TAB>
karaf@root(bundle)>
capabilities classes diag dynamic-import find-class headers info install list refresh requirements resolve restart services start start-level stop
uninstall update watch
karaf@root(bundle)> exit
karaf@root()> camel
karaf@root(camel)> <TAB>
karaf@root(camel)>
backlog-tracer-dump backlog-tracer-info backlog-tracer-start backlog-tracer-stop context-info context-list context-start context-stop endpoint-list route-info route-list route-profile route-reset-stats
route-resume route-show route-start route-stop route-suspend

16.9.3. Unix 系の環境

Karaf コンソールは完全な Unix 系の環境を提供します。

16.9.3.1. help または man

利用できるすべてのコマンドを表示する help コマンドの使用方法についてすでに説明しました。

ただし、help コマンドや、help コマンドのエイリアスである man コマンドを使用して、コマンドの詳細を取得することもできます。--help コマンドのオプションを使用して、別のフォームを使用してコマンドのヘルプを取得することもできます。

以下のコマンドの場合

karaf@root()> help feature:list
karaf@root()> man feature:list
karaf@root()> feature:list --help

すべて同じヘルプ出力を生成します。

DESCRIPTION
        feature:list

        Lists all existing features available from the defined repositories.

SYNTAX
        feature:list [options]

OPTIONS
        --help
                Display this help message
        -o, --ordered
                Display a list using alphabetical order
        -i, --installed
                Display a list of all installed features only
        --no-format
                Disable table rendered output

16.9.3.2. 補完

Tab キーを入力すると、Karaf は補完を試みます。

  • サブシェル
  • コマンド
  • エイリアス
  • コマンド引数
  • コマンドオプション

16.9.3.3. エイリアス

エイリアスは、指定コマンドに関連する別の名前です。

shell:alias コマンドは、新しいエイリアスを作成します。たとえば、実際の feature:list -i コマンドに list-installed-features エイリアスを作成するには、以下を実行できます。

karaf@root()> alias "list-features-installed = { feature:list -i }"
karaf@root()> list-features-installed
Name       | Version | Required | State   | Repository     | Description
------------------------------------------------------------------------------------------------------------------------------
feature    | 4.0.0   | x        | Started | standard-4.0.0 | Features Support
shell      | 4.0.0   | x        | Started | standard-4.0.0 | Karaf Shell
deployer   | 4.0.0   | x        | Started | standard-4.0.0 | Karaf Deployer
bundle     | 4.0.0   | x        | Started | standard-4.0.0 | Provide Bundle support
config     | 4.0.0   | x        | Started | standard-4.0.0 | Provide OSGi ConfigAdmin support
diagnostic | 4.0.0   | x        | Started | standard-4.0.0 | Provide Diagnostic support
instance   | 4.0.0   | x        | Started | standard-4.0.0 | Provide Instance support
jaas       | 4.0.0   | x        | Started | standard-4.0.0 | Provide JAAS support
log        | 4.0.0   | x        | Started | standard-4.0.0 | Provide Log support
package    | 4.0.0   | x        | Started | standard-4.0.0 | Package commands and mbeans
service    | 4.0.0   | x        | Started | standard-4.0.0 | Provide Service support
system     | 4.0.0   | x        | Started | standard-4.0.0 | Provide System support
kar        | 4.0.0   | x        | Started | standard-4.0.0 | Provide KAR (KARaf archive) support
ssh        | 4.0.0   | x        | Started | standard-4.0.0 | Provide a SSHd server on Karaf
management | 4.0.0   | x        | Started | standard-4.0.0 | Provide a JMX MBeanServer and a set of MBeans in

ログイン時に、Apache Karaf コンソールは、エイリアスを作成できる etc/shell.init.script ファイルを読み取ります。Unix の bashrc やプロファイルファイルに似ています。

ld = { log:display $args } ;
lde = { log:exception-display $args } ;
la = { bundle:list -t 0 $args } ;
ls = { service:list $args } ;
cl = { config:list "(service.pid=$args)" } ;
halt = { system:shutdown -h -f $args } ;
help = { *:help $args | more } ;
man = { help $args } ;
log:list = { log:get ALL } ;

ここで、デフォルトで利用可能なエイリアスを確認できます。

  • ld はログを表示する短縮形式です (log:display コマンドのエイリアス)。
  • lde は例外を表示する短縮形式です (log:exception-display コマンドのエイリアス)。
  • la はすべてのバンドルを一覧表示するための短縮形式です (bundle:list -t 0 コマンドのエイリアス) 。
  • ls はすべてのサービスを一覧表示する短縮形式です (service:list コマンドのエイリアス)。
  • cl は全設定を一覧表示するための短縮形式です (config:list コマンドのエイリアス)。
  • halt は Apache Karaf をシャットダウンするための短縮形式です (system:shutdown -h -f コマンドへのエイリアス)。
  • help は、ヘルプを表示する短縮形式です (*:help コマンドのエイリアス)。
  • man は help と同じです (help コマンドのエイリアス)。
  • log:list はすべてのロガーおよびレベルを表示します (log:get ALL コマンドのエイリアス)。

etc/shell.init.script ファイルに、独自のエイリアスを作成できます。

16.9.3.4. キーバインディング

ほとんどの Unix 環境と同様に、Karaf コンソールは一部のキーバインディングをサポートします。

  • コマンド履歴内を移動するための矢印キー
  • Karaf をログアウト/シャットダウンするするための CTRL-D
  • 以前実行したコマンドを検索する CTRL-R
  • 現在の行を削除する CTRL-U

16.9.3.5. パイプ

あるコマンドの出力を別のコマンドへの入力としてパイプすることができます。パイプは | 文字を使用します。

karaf@root()> feature:list |grep -i war
pax-war                       | 4.1.4                            |          | Uninstalled | org.ops4j.pax.web-4.1.4  | Provide support of a full WebContainer
pax-war-tomcat                | 4.1.4                            |          | Uninstalled | org.ops4j.pax.web-4.1.4  |
war                           | 4.0.0                            |          | Uninstalled | standard-4.0.0           | Turn Karaf as a full WebContainer
blueprint-web                 | 4.0.0                            |          | Uninstalled | standard-4.0.0           | Provides an OSGI-aware Servlet ContextListener fo

16.9.3.6. grep, more, find, …​

Karaf コンソールは、Unix 環境と同様のコアコマンドを提供します。

  • shell:alias は既存のコマンドのエイリアスを作成します。
  • shell:cat はファイルまたは URL の内容を表示します。
  • shell:clear は現在のコンソール表示の消去します。
  • shell:completion は現在の補完モードを表示または変更します。
  • shell:date は現在の日付を表示します (必要に応じて形式を使用)。
  • shell:each は引数のリストでクロージャーを実行します。
  • shell:echo は引数を標準出力にエコーおよび出力します。
  • shell:edit は現在のファイルまたは URL のテキストエディターを呼び出します。
  • shell:env はシェルセッション変数の値を表示または設定します。
  • shell:exec はシステムコマンドを実行します。
  • shell:grep は指定のパターンに一致する行を出力します。
  • shell:head は入力の最初の行を表示します
  • shell:history はコマンド履歴を出力します。
  • shell:if はスクリプトで条件 (if、then、else blocks) の使用を可能にします。
  • shell:info は現在の Karaf インスタンスに関するさまざまな情報を出力します。
  • shell:java は Java アプリケーションを実行します。
  • shell:less はファイルページャーです。
  • shell:logout は現行セッションからシェルの切断します。
  • shell:more はファイルページャーです。
  • shell:new は新しい Java オブジェクトを作成します。
  • shell:printf は引数をフォーマットおよび出力します。
  • shell:sleep は短期間スリープ状態にしてからスリープ状態を解除します。
  • shell:sort はすべてのファイルのソートされた連結を標準出力に書き込みます。
  • shell:source はスクリプトに含まれるコマンドを実行します。
  • shell:stack-traces-print は、コマンドの実行によって例外が発生すると、コンソールで完全なスタックトレースを出力します。
  • shell:tac は STDIN をキャプチャーし、文字列として返します。
  • shell:tail は入力の最後の行を表示します。
  • shell:threads は現在のスレッドを出力します。
  • shell:watch は定期的にコマンドを実行し、出力を更新します。
  • shell:wc は各ファイルの改行、単語、およびバイト数を出力します。
  • shell:while は条件が true である間にループします。

コマンドの完全修飾名を使用する必要はありません。一意である限り、コマンド名を直接使用できます。したがって、'shell:head' の代わりに 'head' を使用できます。

ここでも、help コマンドまたは --help オプションを使用して、これらのコマンドの詳細とすべてのオプションを確認できます。

16.9.3.7. スクリプト

Apache Karaf コンソールは、Unix 上の bash または csh と同様に完全なスクリプト言語をサポートします。

each (shell:each) コマンドは、リストで処理を繰り返すことができます。

karaf@root()> list = [1 2 3]; each ($list) { echo $it }
1
2
3
注記

同じループを shell:while コマンドで記述できます。

karaf@root()> a = 0 ; while { %((a+=1) <= 3) } { echo $a }
1
2
3

リストを独自に作成することもできます (前の例のように)。または一部のコマンドはリストを返すこともできます。

コンソールは、$list でアクセス可能な list という名前の「セッション」変数を作成したことに注意してください。

$it 変数は、現在のオブジェクトに対応する暗黙的な変数です (ここではリストの現在の反復処理された値)。

[] でリストを作成すると、Apache Karaf コンソールは Java ArrayList を作成します。つまり、ArrayList オブジェクトで利用可能なメソッドを使用できます (たとえばインスタンスの get や size など) 。

karaf@root()> list = ["Hello" world]; echo ($list get 0) ($list get 1)
Hello world

ここで、オブジェクトのメソッドを呼び出すことは、(object method argument) を直接使用することに注意してください。ここでは ($list get 0)$list.get(0) を意味し、$list は ArrayList になります。

class 表記には、オブジェクトの詳細が表示されます。

karaf@root()> $list class
...
ProtectionDomain     ProtectionDomain  null
 null
 <no principals>
 java.security.Permissions@6521c24e (
 ("java.security.AllPermission" "<all permissions>" "<all actions>")
)


Signers              null
SimpleName           ArrayList
TypeParameters       [E]

特定の型に変数を「キャスト」できます。

karaf@root()> ("hello world" toCharArray)
[h, e, l, l, o,  , w, o, r, l, d]

失敗すると、キャスト例外が表示されます。

karaf@root()> ("hello world" toCharArray)[0]
Error executing command: [C cannot be cast to [Ljava.lang.Object;

shell:source コマンドを使用して、スクリプトを「呼び出し」することができます。

karaf@root> shell:source script.txt
True!

script.txt には以下が含まれます。

foo = "foo"
if { $foo equals "foo" } {
  echo "True!"
}
注記

スペースはスクリプトを書くときに重要です。たとえば、以下のスクリプトは正しくありません。

if{ $foo equals "foo" } ...

これは以下で失敗します。

karaf@root> shell:source script.txt
Error executing command: Cannot coerce echo "true!"() to any of []

if ステートメントの後にスペースがないためです。

エイリアスに関しては、etc/shell.init.script ファイル内に init スクリプトを作成できます。エイリアスを使用してスクリプトの名前を付けることもできます。実際、エイリアスは単なるスクリプトです。

詳細は、『開発者ガイド』の「スクリプト」セクションを参照してください。

16.9.4. セキュリティー

Apache Karaf コンソールは、RBAC (Role Based Access Control) のセキュリティーメカニズムをサポートします。つまり、コンソールに接続しているユーザーに応じて、ユーザーのグループとロールに応じて、いくつかのコマンドを実行する権限を定義したり、引数に許可される値を制限したりできます。

コンソールのセキュリティーについては、本ユーザーガイドのセキュリティーセクションを参照してください。

16.10. プロビジョニング

Apache Karaf は、Karaf 機能の概念を使用したアプリケーションとモジュールのプロビジョニングをサポートします。

16.10.1. アプリケーション

アプリケーションのプロビジョニングにより、すべてのモジュール、設定、および推移的なアプリケーションがインストールされます。

16.10.2. OSGi

OSGi アプリケーションのデプロイメントをネイティブにサポートします。

OSGi アプリケーションは OSGi バンドルのセットです。OSGi バンドルは通常の jar ファイルであり、jar の MANIFEST に追加のメタデータが含まれます。

OSGi では、バンドルは他のバンドルに依存できます。つまり、OSGi アプリケーションをデプロイするには、ほとんどの場合、まずアプリケーションに必要な他の多くのバンドルをデプロイする必要があります。

そのため、これらのバンドルを最初に検索して、バンドルをインストールする必要があります。ここでも、これらの「依存関係」バンドルは、独自の依存関係を満たすために他のバンドルが必要になる場合があります。

通常、アプリケーションには設定が必要です (ユーザーガイドの「設定」セクション を参照)。したがって、アプリケーションを起動する前に、依存関係バンドルに加えて、設定を作成またはデプロイする必要があります。

ご覧のとおり、アプリケーションのプロビジョニングは非常に長く、厳しい場合があります。

16.10.3. 機能およびリゾルバー

Apache Karaf は、アプリケーションをプロビジョニングするためのシンプルで柔軟な方法を提供します。

Apache Karaf では、アプリケーションのプロビジョニングは Apache Karaf の「機能」です。

機能は、アプリケーションを次のように記述します。

  • 名前
  • バージョン
  • 任意の説明 (最終的には長い説明)
  • バンドルのセット
  • 設定または設定ファイルのセット (任意)
  • 依存関係機能のセット (任意)

機能をインストールすると、Apache Karaf は機能に記載されているすべてのリソースをインストールします。つまり、機能で説明するすべてのバンドル、設定、および依存関係機能を自動的に解決し、インストールすることを意味します。

機能リゾルバーはサービスの要件を確認し、要件に一致するサービスを提供するバンドルをインストールします。デフォルトモードでは、「新しいスタイル」features リポジトリー (基本的には、スキーマが 1.3.0 以上の機能リポジトリ ー XML) に対してのみこの動作が有効になります。これは、「旧スタイル」の features リポジトリー (Karaf 2 または 3 から) には適用されません。

serviceRequirements プロパティーを使用して、etc/org.apache.karaf.features.cfg ファイルでサービス要件強制モードを変更できます。

serviceRequirements=default

以下の値を使用できます。

  • disable:「旧スタイル」と「新スタイル」の features リポジトリーの両方でサービス要件は完全に無視されます。
  • default: サービス要件は「旧スタイル」の features リポジトリーで無視され、「新スタイル」の features リポジトリーに対して有効になります。
  • enforce: サービス要件は「旧スタイル」および「新しいスタイル」features リポジトリーに対して常に検証されます。

さらに、この機能は要件を定義することも可能です。その場合、Karaf は、要件を満たす機能を提供する追加のバンドルまたは機能を自動的に追加できます。

機能には、install、start、stop、update、uninstall という完全なライフサイクルがあります。

16.10.4. features リポジトリー

機能は、features XML 記述子で記述されます。この XML ファイルには、一連の機能の記述が含まれています。

features XML 記述子の名前は「features リポジトリー」です。機能をインストールする前に、機能を提供する features リポジトリーを登録する必要があります (後で説明するように feature:repo-add コマンドまたは FeatureMBean を使用します)。

たとえば、以下の XML ファイル (または「features リポジトリー」) は、feature1 および feature2 機能を記述します。

<features xmlns="http://karaf.apache.org/xmlns/features/v1.3.0">
  <feature name="feature1" version="1.0.0">
    <bundle>...</bundle>
    <bundle>...</bundle>
  </feature>
  <feature name="feature2" version="1.1.0">
    <feature>feature1</feature>
    <bundle>...</bundle>
  </feature>
</features>

features XML にはスキーマがあることに注意してください。詳細は、ユーザーガイドの「features XML スキーマ」セクションを参照してください。feature1 機能はバージョン 1.0.0 で使用でき、2 つのバンドルが含まれます。<bundle/> 要素には、バンドルアーティファクトへの URL が含まれます (詳細は「アーティファクトリポジトリーおよび URL」セクションを参照) 。feature1 機能をインストールする場合 (後で説明するように feature:install または FeatureMBean を使用)、Apache Karaf によって自動的に記述された 2 つのバンドルがインストールされます。feature2 機能はバージョン 1.1.0 で利用でき、feature1 機能およびバンドルへの参照が含まれます。<feature/> 要素には機能の名前が含まれます。特定機能のバージョンは、version 属性を <feature/> 要素に使用して定義できます (<feature version="1.0.0">feature1</feature>)。version 属性が指定されていない場合、Apache Karaf は利用可能な最新バージョンをインストールします。feature2 機能をインストールする場合 (後で説明するように feature:install または FeatureMBean を使用)、Apache Karaf は feature1 (すでにインストールされていない場合) およびバンドルを自動的にインストールします。

features リポジトリーは、features XML ファイルへの URL を使用して登録されます。

機能の状態は Apache Karaf キャッシュ (KARAF_DATA フォルダー内) に保存されます。Apache Karaf は再起動でき、以前にインストールした機能は、再起動後も引き続きインストールされた状態を保ち、利用できます。クリーンな再起動を行ったり、Apache Karaf キャッシュを削除する場合 (KARAF_DATA フォルダーを削除する)、以前に登録された features リポジトリーとインストールされた機能はすべて失われます。手作業で features リポジトリーを再度登録し、機能を再度インストールする必要があります。この動作を防ぐには、機能をブート機能として指定します。

16.10.5. ブート機能

一部の機能を、ブート機能として記述できます。feature:install または FeatureMBean を使用して事前にインストールされていない場合でも、ブート機能は Apache Karaf によって自動的にインストールされます。

Apache Karaf の機能設定は etc/org.apache.karaf.features.cfg 設定ファイルにあります。

この設定ファイルには、ブート機能の定義に使用する 2 つのプロパティーが含まれます。

  • featuresRepositoriesには features リポジトリー (features XML) URL のリスト (コンマ区切り) が含まれます。
  • featuresBoot には起動時にインストールする機能の一覧 (コンマ区切り) が含まれます。

16.10.6. 機能のアップグレード

同じ機能 (同じ SNAPSHOT バージョンまたは別のバージョン) をインストールして、リリースを更新できます。

機能のライフサイクルにより、機能のステータス (started、stopped など) を制御できます。

シミュレーションを使用して、更新の実行内容を確認することもできます。

16.10.7. オーバーライド

機能に定義されているバンドルは、etc/overrides.properties ファイルを使用してオーバーライドできます。ファイルの各行は 1 つのオーバーライドを定義します。構文は <bundle-uri>[;range="[min,max)"] です。オーバーライドのバージョンがオーバーライドされたバンドルのバージョンよりも大きく、範囲が一致する場合、指定されたバンドルは、機能定義のすべてのバンドルを同じシンボリック名でオーバーライドします。範囲が指定されていない場合は、マイクロバージョンレベルでの互換性が想定されます。

たとえば、オーバーライド mvn:org.ops4j.pax.logging/pax-logging-service/1.8.5 は pax-logging-service 1.8.3 をオーバーライドしますが、1.8.6 や 1.7.0 はオーバーライドされません。

16.10.8. 機能バンドル

16.10.8.1. 開始レベル

デフォルトでは、機能によってデプロイされるバンドルの開始レベルは、karaf.startlevel.bundle プロパティーの etc/config.properties 設定ファイルで定義された値と等しくなります。

この値を、features XML の <bundle/> 要素の start-level 属性で「上書き」することができます。

  <feature name="my-project" version="1.0.0">
    <bundle start-level="80">mvn:com.mycompany.myproject/myproject-dao</bundle>
    <bundle start-level="85">mvn:com.mycompany.myproject/myproject-service</bundle>
  </feature>

start-level 属性は、それを使用するバンドルの前に myproject-dao バンドルが開始されるようにします。

start-level を使用する代わりに、必要なパッケージまたはサービスを定義することで、OSGi フレームワークに依存関係が何であるかを知らせる方がよいでしょう。これは、start-level の設定よりも堅牢です。

16.10.8.2. シミュレーション、開始、および停止

-t オプションを feature:install コマンドに使用して、機能のインストールをシミュレートできます。

バンドルは、起動せずにインストールできます。デフォルトでは、機能のバンドルは自動的に開始されます。

機能ではバンドルが自動的に起動しないように指定できます (バンドルは解決済み状態のままになります)。これを行うには、<bundle/> 要素で start 属性を false に指定します。

  <feature name="my-project" version="1.0.0">
    <bundle start-level="80" start="false">mvn:com.mycompany.myproject/myproject-dao</bundle>
    <bundle start-level="85" start="false">mvn:com.mycompany.myproject/myproject-service</bundle>
  </feature>

16.10.8.3. 依存関係

<bundle/> 要素で dependency 属性を true に設定して、バンドルに依存関係としてフラグを付けることができます。

この情報は、インストールするバンドルの完全リストを計算するためにリゾルバーによって使用されます。

16.10.9. 依存する機能

機能は、その他の機能のセットに依存できます。

  <feature name="my-project" version="1.0.0">
    <feature>other</feature>
    <bundle start-level="80" start="false">mvn:com.mycompany.myproject/myproject-dao</bundle>
    <bundle start-level="85" start="false">mvn:com.mycompany.myproject/myproject-service</bundle>
  </feature>

my-project 機能をインストールすると、other 機能も自動的にインストールされます。

依存する機能にバージョン範囲を定義できます。

<feature name="spring-dm">
  <feature version="[2.5.6,4)">spring</feature>
  ...
</feature>

範囲で利用可能な最新バージョンを持つ機能がインストールされます。

1 つのバージョンを指定すると、範囲の上限はないとみなされます。

何も指定されていない場合、利用可能な最新バージョンがインストールされます。

正確なバージョンを指定するには、[3.1,3.1] のように範囲を指定します。

16.10.9.1. 機能の前提条件

前提条件機能は、特別な種類の依存関係です。prerequisite 属性を依存する機能タグに追加する場合、実際の機能をインストールする前に、依存機能でのバンドルのインストールとアクティベーションが強制されます。これは、特定の機能に登録されたバンドルが wrap または war などの事前インストールされた URL を使用しない場合に便利です。

16.10.10. 機能設定

features XML の <config/> 要素を使用すると、機能は設定を作成したり入力したりできます (設定 PID によって識別)。

<config name="com.foo.bar">
  myProperty = myValue
</config>

<config/> 要素の name 属性は、設定 PID に対応します (詳細は「設定」セクションを参照してください) 。

この機能のインストールは、com.foo.bar.cfg という名前のファイルを etc フォルダーにドロップするのと同じ効果があります。

<config/> 要素の内容は、key=value 標準に従ったプロパティーのセットになります。

16.10.11. 機能設定ファイル

この機能は、<config/> 要素を使用する代わりに <configfile/> 要素を指定できます。

<configfile finalname="/etc/myfile.cfg" override="false">URL</configfile>

(<config/> 要素を使用する場合のように) Apache Karaf 設定レイヤーを直接操作する代わりに、<configfile/> 要素は URL で指定されたファイルを直接取得し、finalname 属性で指定された場所にファイルをコピーします。

指定しない場合、場所は KARAF_BASE 変数からの相対位置になります。${karaf.home}、${karaf.base}、${karaf.etc}、またはシステムプロパティーなどの変数を使用することもできます。

たとえば、以下のようになります。

<configfile finalname="${karaf.etc}/myfile.cfg" override="false">URL</configfile>

ファイルが目的の場所にすでに存在する場合は、既存のファイルにカスタマイズが含まれている可能性があるため、そのファイルは保持され、設定ファイルのデプロイメントはスキップされます。この動作は、override を true に設定してオーバーライドできます。

ファイル URL は Apache Karaf でサポートされる URL です (詳細は、ユーザーガイドの 「アーティファクトリポジトリーおよび URL」を参照してください) 。

16.10.11.1. 要件

機能は、想定される要件を指定することもできます。機能リゾルバーは要件を満たそうとします。そのため、これは機能およびバンドル機能を確認し、要件を満たすためにバンドルを自動的にインストールします。

たとえば、機能に以下を含めることができます。

<requirement>osgi.ee;filter:=&quot;(&amp;(osgi.ee=JavaSE)(!(version&gt;=1.8)))&quot;</requirement>

この要件は、JDK のバージョンが 1.8 でない場合のみ (よって基本的に 1.7) 、機能が動作すること指定します。

機能リゾルバーは、オプションの依存関係が満たされるときにバンドルを更新し、オプションのインポートを再度ワイヤーすることもできます。

16.10.12. コマンド

16.10.12.1. feature:repo-list

feature:repo-list コマンドは、登録されたすべての features リポジトリーを一覧表示します。

karaf@root()> feature:repo-list
Repository               | URL
--------------------------------------------------------------------------------------
org.ops4j.pax.cdi-0.12.0 | mvn:org.ops4j.pax.cdi/pax-cdi-features/0.12.0/xml/features
org.ops4j.pax.web-4.1.4  | mvn:org.ops4j.pax.web/pax-web-features/4.1.4/xml/features
standard-4.0.0           | mvn:org.apache.karaf.features/standard/4.0.0/xml/features
enterprise-4.0.0         | mvn:org.apache.karaf.features/enterprise/4.0.0/xml/features
spring-4.0.0             | mvn:org.apache.karaf.features/spring/4.0.0/xml/features

各リポジトリーには、名前と features XML への URL があります。

Apache Karaf は、features リポジトリーの URL を登録する際に機能 XML を解析します (後ほど説明する feature:repo-add コマンドまたは FeatureMBean を使用します)。Apache Karaf が features リポジトリーの URL をリロードするよう強制する場合 (たとえば機能定義を更新)、-r オプションを使用できます。

karaf@root()> feature:repo-list -r
Reloading all repositories from their urls

Repository               | URL
--------------------------------------------------------------------------------------
org.ops4j.pax.cdi-0.12.0 | mvn:org.ops4j.pax.cdi/pax-cdi-features/0.12.0/xml/features
org.ops4j.pax.web-4.1.4  | mvn:org.ops4j.pax.web/pax-web-features/4.1.4/xml/features
standard-4.0.0           | mvn:org.apache.karaf.features/standard/4.0.0/xml/features
enterprise-4.0.0         | mvn:org.apache.karaf.features/enterprise/4.0.0/xml/features
spring-4.0.0             | mvn:org.apache.karaf.features/spring/4.0.0/xml/features

16.10.12.2. feature:repo-add

features リポジトリーを登録する (Apache Karaf で新しい機能を利用できるようにする) には、feature:repo-add コマンドを使用する必要があります。

feature:repo-add コマンドには、name/url 引数が必要です。この引数は、以下を受け入れます。

  • features リポジトリーの URL。features XML ファイルへの直接 URL になります。ユーザーガイドの「アーティファクトリポジトリーおよび URL」セクションで説明されている URL はサポートされます。
  • etc/org.apache.karaf.features.repos.cfg 設定ファイルで定義された features リポジトリー名。

etc/org.apache.karaf.features.repos.cfg は、「事前インストールされた/利用可能な」features リポジトリーの一覧を定義します。

################################################################################
#
#    Licensed to the Apache Software Foundation (ASF) under one or more
#    contributor license agreements.  See the NOTICE file distributed with
#    this work for additional information regarding copyright ownership.
#    The ASF licenses this file to You under the Apache License, Version 2.0
#    (the "License"); you may not use this file except in compliance with
#    the License.  You may obtain a copy of the License at
#
#       http://www.apache.org/licenses/LICENSE-2.0
#
#    Unless required by applicable law or agreed to in writing, software
#    distributed under the License is distributed on an "AS IS" BASIS,
#    WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
#    See the License for the specific language governing permissions and
#    limitations under the License.
#
################################################################################

#
# This file describes the features repository URL
# It could be directly installed using feature:repo-add command
#
enterprise=mvn:org.apache.karaf.features/enterprise/LATEST/xml/features
spring=mvn:org.apache.karaf.features/spring/LATEST/xml/features
cellar=mvn:org.apache.karaf.cellar/apache-karaf-cellar/LATEST/xml/features
cave=mvn:org.apache.karaf.cave/apache-karaf-cave/LATEST/xml/features
camel=mvn:org.apache.camel.karaf/apache-camel/LATEST/xml/features
camel-extras=mvn:org.apache-extras.camel-extra.karaf/camel-extra/LATEST/xml/features
cxf=mvn:org.apache.cxf.karaf/apache-cxf/LATEST/xml/features
cxf-dosgi=mvn:org.apache.cxf.dosgi/cxf-dosgi/LATEST/xml/features
cxf-xkms=mvn:org.apache.cxf.services.xkms/cxf-services-xkms-features/LATEST/xml
activemq=mvn:org.apache.activemq/activemq-karaf/LATEST/xml/features
jclouds=mvn:org.apache.jclouds.karaf/jclouds-karaf/LATEST/xml/features
openejb=mvn:org.apache.openejb/openejb-feature/LATEST/xml/features
wicket=mvn:org.ops4j.pax.wicket/features/LATEST/xml/features
hawtio=mvn:io.hawt/hawtio-karaf/LATEST/xml/features
pax-cdi=mvn:org.ops4j.pax.cdi/pax-cdi-features/LATEST/xml/features
pax-jdbc=mvn:org.ops4j.pax.jdbc/pax-jdbc-features/LATEST/xml/features
pax-jpa=mvn:org.ops4j.pax.jpa/pax-jpa-features/LATEST/xml/features
pax-web=mvn:org.ops4j.pax.web/pax-web-features/LATEST/xml/features
pax-wicket=mvn:org.ops4j.pax.wicket/pax-wicket-features/LATEST/xml/features
ecf=http://download.eclipse.org/rt/ecf/latest/site.p2/karaf-features.xml
decanter=mvn:org.apache.karaf.decanter/apache-karaf-decanter/LATEST/xml/features

機能のリポジトリー名は、feature:repo-add コマンドに直接指定できます。PAX JDBC をインストールするには、以下を実行できます。

karaf@root()> feature:repo-add pax-jdbc
Adding feature url mvn:org.ops4j.pax.jdbc/pax-jdbc-features/LATEST/xml/features

オプションの version 引数を指定しないと、Apache Karaf は利用可能な features リポジトリーの最新バージョンをインストールします。version 引数でターゲットバージョンを指定できます。

karaf@root()> feature:repo-add pax-jdbc 1.3.0
Adding feature url mvn:org.ops4j.pax.jdbc/pax-jdbc-features/1.3.0/xml/features

etc/org.apache.karaf.features.repos.cfg 設定ファイルで定義された features リポジトリー名を提供する代わりに、 features リポジトリーの URL を feature:repo-add コマンドに直接指定できます。

karaf@root()> feature:repo-add mvn:org.ops4j.pax.jdbc/pax-jdbc-features/1.3.0/xml/features
Adding feature url mvn:org.ops4j.pax.jdbc/pax-jdbc-features/1.3.0/xml/features

デフォルトでは、feature:repo-add コマンドは features リポジトリーを登録するだけで、機能はインストールしません。-i オプションを指定すると、feature:repo-add コマンドは features リポジトリーを登録し、この features リポジトリーに記述されているすべての機能をインストールします。

karaf@root()> feature:repo-add -i pax-jdbc

16.10.12.3. feature:repo-refresh

Apache Karaf は、登録時に features リポジトリー XML を解析します (feature:repo-add コマンドまたは FeatureMBean を使用)。features リポジトリーの XML が変更された場合は、feaatures リポジトリーを更新して変更をロードするように Apache Karaf に指示する必要があります。

feature:repo-refresh コマンドは features リポジトリーを更新します。

引数がないと、コマンドはすべての features リポジトリーを更新します。

karaf@root()> feature:repo-refresh
Refreshing feature url mvn:org.ops4j.pax.cdi/pax-cdi-features/0.12.0/xml/features
Refreshing feature url mvn:org.ops4j.pax.web/pax-web-features/4.1.4/xml/features
Refreshing feature url mvn:org.apache.karaf.features/standard/4.0.0/xml/features
Refreshing feature url mvn:org.apache.karaf.features/enterprise/4.0.0/xml/features
Refreshing feature url mvn:org.apache.karaf.features/spring/4.0.0/xml/features

すべての features リポジトリーを更新する代わりに、URL または features リポジトリー名 (およびオプションでバージョン) を指定して、更新する features リポジトリーを指定できます。

karaf@root()> feature:repo-refresh mvn:org.apache.karaf.features/standard/4.0.0/xml/features
Refreshing feature url mvn:org.apache.karaf.features/standard/4.0.0/xml/features
karaf@root()> feature:repo-refresh pax-jdbc
Refreshing feature url mvn:org.ops4j.pax.jdbc/pax-jdbc-features/LATEST/xml/features

16.10.12.4. feature:repo-remove

feature:repo-remove コマンドは、登録した features リポジトリーから features リポジトリーを削除します。

feature:repo-remove コマンドには、引数が必要です。

  • features リポジトリー名 (feature:repo-list コマンド出力のリポジトリーの列に表示)
  • features リポジトリー URL (feature:repo-list コマンド出力の URL コラムに表示)
karaf@root()> feature:repo-remove org.ops4j.pax.jdbc-1.3.0
karaf@root()> feature:repo-remove mvn:org.ops4j.pax.jdbc/pax-jdbc-features/1.3.0/xml/features

デフォルトでは、feature:repo-remove コマンドは、登録した機能から features リポジトリーを削除します。これは、features リポジトリーによって提供される機能をアンインストールしません。

-u オプションを使用すると、feature:repo-remove コマンドは features リポジトリーによって記述されたすべての機能をアンインストールします。

karaf@root()> feature:repo-remove -u org.ops4j.pax.jdbc-1.3.0

16.10.12.5. feature:list

feature:list コマンドは、利用可能なすべての機能を一覧表示します (登録された異なる features リポジトリーによって提供) 。

Name                          | Version                          | Required | State       | Repository               | Description
-------------------------------------------------------------------------------------------------------------------------------------------------------------------------
pax-cdi                       | 0.12.0                           |          | Uninstalled | org.ops4j.pax.cdi-0.12.0 | Provide CDI support
pax-cdi-1.1                   | 0.12.0                           |          | Uninstalled | org.ops4j.pax.cdi-0.12.0 | Provide CDI 1.1 support
pax-cdi-1.2                   | 0.12.0                           |          | Uninstalled | org.ops4j.pax.cdi-0.12.0 | Provide CDI 1.2 support
pax-cdi-weld                  | 0.12.0                           |          | Uninstalled | org.ops4j.pax.cdi-0.12.0 | Weld CDI support
pax-cdi-1.1-weld              | 0.12.0                           |          | Uninstalled | org.ops4j.pax.cdi-0.12.0 | Weld CDI 1.1 support
pax-cdi-1.2-weld              | 0.12.0                           |          | Uninstalled | org.ops4j.pax.cdi-0.12.0 | Weld CDI 1.2 support
pax-cdi-openwebbeans          | 0.12.0                           |          | Uninstalled | org.ops4j.pax.cdi-0.12.0 | OpenWebBeans CDI support
pax-cdi-web                   | 0.12.0                           |          | Uninstalled | org.ops4j.pax.cdi-0.12.0 | Web CDI support
pax-cdi-1.1-web               | 0.12.0                           |          | Uninstalled | org.ops4j.pax.cdi-0.12.0 | Web CDI 1.1 support
...

名前をアルファベット順に並べたい場合は、-o オプションを使用できます。

karaf@root()> feature:list -o
Name                          | Version                          | Required | State       | Repository               | Description
-------------------------------------------------------------------------------------------------------------------------------------------------------------------------
deltaspike-core               | 1.2.1                            |          | Uninstalled | org.ops4j.pax.cdi-0.12.0 | Apache Deltaspike core support
deltaspike-data               | 1.2.1                            |          | Uninstalled | org.ops4j.pax.cdi-0.12.0 | Apache Deltaspike data support
deltaspike-jpa                | 1.2.1                            |          | Uninstalled | org.ops4j.pax.cdi-0.12.0 | Apache Deltaspike jpa support
deltaspike-partial-bean       | 1.2.1                            |          | Uninstalled | org.ops4j.pax.cdi-0.12.0 | Apache Deltaspike partial bean support
pax-cdi                       | 0.12.0                           |          | Uninstalled | org.ops4j.pax.cdi-0.12.0 | Provide CDI support
pax-cdi-1.1                   | 0.12.0                           |          | Uninstalled | org.ops4j.pax.cdi-0.12.0 | Provide CDI 1.1 support
pax-cdi-1.1-web               | 0.12.0                           |          | Uninstalled | org.ops4j.pax.cdi-0.12.0 | Web CDI 1.1 support
pax-cdi-1.1-web-weld          | 0.12.0                           |          | Uninstalled | org.ops4j.pax.cdi-0.12.0 | Weld Web CDI 1.1 support
pax-cdi-1.1-weld              | 0.12.0                           |          | Uninstalled | org.ops4j.pax.cdi-0.12.0 | Weld CDI 1.1 support
pax-cdi-1.2                   | 0.12.0                           |          | Uninstalled | org.ops4j.pax.cdi-0.12.0 | Provide CDI 1.2 support
...

デフォルトでは、feature:list コマンドは現在の状態 (インストール済みまたはインストールされていない) に関わらず、すべての機能を表示します。

-i オプションを使用すると、インストールされた機能だけが表示されます。

karaf@root()> feature:list -i
Name            | Version | Required | State   | Repository     | Description
-------------------------------------------------------------------------------------------------------------------
aries-proxy     | 4.0.0   |          | Started | standard-4.0.0 | Aries Proxy
aries-blueprint | 4.0.0   | x        | Started | standard-4.0.0 | Aries Blueprint
feature         | 4.0.0   | x        | Started | standard-4.0.0 | Features Support
shell           | 4.0.0   | x        | Started | standard-4.0.0 | Karaf Shell
shell-compat    | 4.0.0   | x        | Started | standard-4.0.0 | Karaf Shell Compatibility
deployer        | 4.0.0   | x        | Started | standard-4.0.0 | Karaf Deployer
bundle          | 4.0.0   | x        | Started | standard-4.0.0 | Provide Bundle support
config          | 4.0.0   | x        | Started | standard-4.0.0 | Provide OSGi ConfigAdmin support
diagnostic      | 4.0.0   | x        | Started | standard-4.0.0 | Provide Diagnostic support
instance        | 4.0.0   | x        | Started | standard-4.0.0 | Provide Instance support
jaas            | 4.0.0   | x        | Started | standard-4.0.0 | Provide JAAS support
log             | 4.0.0   | x        | Started | standard-4.0.0 | Provide Log support
package         | 4.0.0   | x        | Started | standard-4.0.0 | Package commands and mbeans
service         | 4.0.0   | x        | Started | standard-4.0.0 | Provide Service support
system          | 4.0.0   | x        | Started | standard-4.0.0 | Provide System support
kar             | 4.0.0   | x        | Started | standard-4.0.0 | Provide KAR (KARaf archive) support
ssh             | 4.0.0   | x        | Started | standard-4.0.0 | Provide a SSHd server on Karaf
management      | 4.0.0   | x        | Started | standard-4.0.0 | Provide a JMX MBeanServer and a set of MBeans in
wrap            | 0.0.0   | x        | Started | standard-4.0.0 | Wrap URL handler

16.10.12.6. feature:install

feature:install コマンドは機能をインストールします。

feature 引数が必要です。feature 引数は、機能の名前または機能の名前/バージョンです。機能の名前のみが提供されている場合 (バージョンではなく)、利用可能な最新バージョンがインストールされます。

karaf@root()> feature:install eventadmin

-t または --simulate オプションを使用してインストールをシミュレートできます。これは、何が行われるかを表示するだけで、実行はされません。

karaf@root()> feature:install -t -v eventadmin
Adding features: eventadmin/[4.0.0,4.0.0]
No deployment change.
  Managing bundle:
    org.apache.felix.metatype / 1.0.12

インストールする機能バージョンを指定できます。

karaf@root()> feature:install eventadmin/4.0.0

デフォルトでは、feature:install コマンドは詳細ではありません。feature:install コマンドによって実行されるアクションの詳細を知りたい場合は、-v オプションを使用できます。

karaf@root()> feature:install -v eventadmin
Adding features: eventadmin/[4.0.0,4.0.0]
No deployment change.
Done.

機能に、すでにインストールされているバンドルが含まれている場合、Apache Karaf はこのバンドルを更新します。この更新によって、実行中の他のアプリケーションに問題が発生することがあります。インストールされたバンドルの自動更新を無効にする場合は、-r オプションを使用できます。

karaf@root()> feature:install -v -r eventadmin
Adding features: eventadmin/[4.0.0,4.0.0]
No deployment change.
Done.

-s または --no-auto-start オプションを使用して、機能によってインストールされたバンドルを開始しないよう指定できます。

karaf@root()> feature:install -s eventadmin

16.10.12.7. feature:start

デフォルトでは、機能をインストールすると自動的にインストールされます。ただし、-s オプションを feature:install コマンドに指定できます。

機能をインストールすると (起動したかどうかに関わらず)、機能で定義されているバンドルによって提供されるすべてのパッケージが使用可能になり、他のバンドルのワイヤリングに使用できます。

機能を起動すると、すべてのバンドルが起動されるため、機能よってサービスも公開されます。

16.10.12.8. feature:stop

機能を停止することもできます。つまり、機能によって提供されるすべてのサービスが停止され、サービスレジストリーから削除されます。ただし、パッケージはワイヤリングで引き続き利用できます (バンドルは解決済み状態です)。

16.10.12.9. feature:uninstall

feature:uninstall コマンドは機能をアンインストールします。feature:install コマンドと同様に、feature:uninstall コマンドには feature 引数が必要です。feature 引数は、機能の名前または機能の名前/バージョンです。機能の名前のみが提供されている場合 (バージョンではなく)、利用可能な最新バージョンがインストールされます。

karaf@root()> feature:uninstall eventadmin

機能リゾルバは、機能のアンインストール中に関与します。アンインストールされた機能によってインストールされた推移的な機能は、他の機能で使用されなければ、それ自体でアンインストールできます。

16.10.13. デプロイヤー

deploy フォルダーに直接ファイルをドロップすることで features XML を「ホットデプロイ」できます。

Apache Karaf は機能デプロイヤーを提供します。

デプロイフォルダーに features XML をドロップすると、機能デプロイヤー次を行います: * features XML を features リポジトリーとして登録。* install 属性が auto に設定された機能は機能デプロイヤーによって自動的にインストールされます。

たとえば、deploy フォルダーに以下の XML をドロップすると feature1 と feature2 が自動的にインストールされますが、feature3 はインストールされません。

<?xml version="1.0" encoding="UTF-8"?>
<features name="my-features" xmlns="http://karaf.apache.org/xmlns/features/v1.3.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
        xsi:schemaLocation="http://karaf.apache.org/xmlns/features/v1.3.0 http://karaf.apache.org/xmlns/features/v1.3.0">

    <feature name="feature1" version="1.0" install="auto">
        ...
    </feature>

    <feature name="feature2" version="1.0" install="auto">
        ...
    </feature>

    <feature name="feature3" version="1.0">
        ...
    </feature>

</features>

16.10.14. JMX FeatureMBean

JMX レイヤーには、機能および機能リポジトリーの管理専用の MBean である FeatureMBean があります。

FeatureMBean オブジェクト名は org.apache.karaf:type=feature,name=* です。

16.10.14.1. 属性

FeatureMBean は、以下の 2 つの属性を提供します。

  • Features は、利用可能なすべての機能の表形式のデータセットです。
  • Repositories は、すべての登録済み features リポジトリーの表形式のデータセットです。

Repositories 属性は、以下の情報を提供します。

  • Name は features リポジトリーの名前です。
  • Uri はこのリポジトリーの機能 XML に対する URI です。
  • Features この feature リポジトリーによって提供されるすべての機能 (名前およびバージョン) の表形式のデータセットです。
  • Repositories は、この feature リポジトリーに「インポートされた」features リポジトリーの表形式のデータセットです。

Features 属性は、以下の情報を提供します。

  • Name は機能の名前です。
  • Version は機能のバージョンです。
  • Installed はブール値です。true の場合、この機能が現在インストールされていることを意味します。
  • Bundles は機能に記述されている全バンドル (バンドル URL) の表形式のデータセットです。
  • Configurations は、機能に記述されているすべての設定の表形式のデータセットです。
  • Configuration Files は、機能に記述されているすべての設定ファイルの表形式のデータセットです。
  • Dependencies は、機能に記述されているすべての依存する機能の表形式のデータセットです。

16.10.14.2. 操作

  • addRepository(url) url で features リポジトリーを追加します。url は、feature:repo-add コマンドとしての name にすることができます。
  • addRepository(url, install)url で features リポジトリーを追加し、install が true の場合はすべてのバンドルを自動的にインストールします。url は、feature:repo-add コマンドと同様に name にすることができます。
  • removeRepository(url)url で features リポジトリーを削除します。url は、feature:repo-remove コマンドとしての name にすることができます。
  • installFeature(name)name で機能をインストールします。
  • installFeature(name, version)name および version で機能をインストールします。
  • installFeature(name, noClean, noRefresh) は、障害発生時にバンドルを消去せず、バンドルをクリーニングせずに name で機能をインストールします。
  • installFeature(name, version, noClean, noRefresh) は、障害発生時にバンドルをクリーニングせず、すでにインストールされたバンドルを更新せず、name および version で機能をインストールします。
  • uninstallFeature(name)name で機能をアンインストールします。
  • uninstallFeature(name, version)name および version で機能をアンインストールします。

16.10.14.3. 通知

FeatureMBean は、2 種類の通知を送信します (サブスクライブおよび反応できる)。

  • features レポジトリーの変更時 (追加または削除)
  • 機能が変更されたとき (インストールまたはアンインストール)。

第17章 リモート接続を使用したコンテナーの管理

ローカルコンソールを使用してコンテナーを管理することは必ずしも意味がありません。Red Hat Fuse には、コンテナーをリモートで管理する方法が複数あります。リモートコンテナーのコマンドコンソールを使用するか、リモートクライアントを起動できます。

17.1. リモートアクセスのためのコンテナーの設定

17.1.1. 概要

Red Hat Fuse ランタイムをデフォルトモードまたは 「サーバーモードでのランタイムの起動」 で起動する場合、他の Fuse コンソールから SSH 経由でアクセスできるリモートコンソールが有効になります。リモートコンソールは、ローカルコンソールのすべての機能を提供し、リモートユーザーがコンテナーと、そのコンテナー内で実行されているサービスを完全に制御できるようにします。

注記

「クライアントモードでのランタイムの起動」 で実行される場合、Fuse ランタイムはリモートコンソールを無効にします。

17.1.2. リモートアクセスのためのスタンドアロンコンテナーの設定

SSH ホスト名とポート番号は INSTALL_DIR/etc/org.apache.karaf.shell.cfg 設定ファイルで設定されます。リモートアクセスのポートの変更 に、使用するポートを 8102 に変更する設定例を示します。

リモートアクセスのポートの変更

sshPort=8102
sshHost=0.0.0.0

17.2. リモートでの接続と切断

リモートコンテナーに接続する別の方法は 2 つあります。Red Hat Fuse コマンドシェルをすでに実行している場合は、コンソールコマンドを呼び出してリモートコンテナーに接続できます。または、コマンドラインでユーティリティーを直接実行して、リモートコンテナーに接続することもできます。

17.2.1. リモートコンテナーからスタンドアロンコンテナーへの接続

17.2.1.1. 概要

コンテナーのコマンドコンソールを使用して、リモートコンテナーにアクセスできます。SSH を使用すると、ローカルコンテナーのコンソールはリモートコンテナーに接続し、リモートコンテナーのコマンドコンソールとして機能します。

17.2.1.2. ssh:ssh コンソールコマンドの使用

ssh:ssh コンソールを使用して、リモートコンテナーのコンソールに接続します。

ssh:ssh コマンド構文

ssh:ssh -l username -P password -p port hostname

-l
リモートコンテナーへの接続に使用されるユーザー名。admin 権限を持つ有効な JAAS ログインクレデンシャルを使用します。
-P
リモートコンテナーへの接続に使用されるパスワード。
-p
必要なコンテナーのリモートコンソールへのアクセスに使用される SSH ポート。デフォルト値は 8101 です。ポート番号の変更に関する情報は、「リモートアクセスのためのスタンドアロンコンテナーの設定」 を参照してください。
hostname
リモートコンテナーが実行されているマシンのホスト名。ホスト名の変更に関する詳細は、「リモートアクセスのためのスタンドアロンコンテナーの設定」 を参照してください。
警告

etc/users.properties ファイルでユーザー名とパスワードをカスタマイズすることが推奨されます。

注記

リモートコンテナーが Oracle VM Server for SPARC インスタンスにデプロイされている場合は、デフォルトの SSH ポート値 8101 はすでに論理ドメインマネージャーデーモンによって使用されている可能性が高くなります。この場合、「リモートアクセスのためのスタンドアロンコンテナーの設定」 の説明に従って、コンテナーの SSH ポートを再設定する必要があります。

正しいコンテナーに接続していることを確認するには、Karaf コンソールプロンプトで shell:info を入力します。これにより、現在接続されているインスタンスに関する情報が返されます。

17.2.1.3. リモートコンソールからの切断

リモートコンソールから切断するには、logout を入力するか、プロンプトで Ctrl+D を押します。

リモートコンテナーから切断され、コンソールは再びローカルコンテナーを管理できるようになります。

17.2.2. クライアントコマンドラインユーティリティーを使用したコンテナーへの接続

17.2.2.1. リモートクライアントの使用

リモートクライアントを使用すると、完全な Fuse コンテナーをローカルで起動せずに、リモート Red Hat Fuse コンテナーに安全に接続できます。

たとえば、同じマシンでサーバーモードで実行されている Fuse インスタンスに即座に接続するには、コマンドプロンプトを開いて、client[.bat] スクリプトを実行します (InstallDir/bin ディレクトリー内にあります)。

client

通常は、リモートインスタンスに接続するためのホスト名、ポート、ユーザー名、およびパスワードを指定します。テストスイートなど、大規模なスクリプト内でクライアントを使用している場合は、以下のようにコンソールコマンドを追加できます。

client -a 8101 -h hostname -u username -p password shell:info

または、-p オプションを省略した場合は、パスワードの入力を求められます。

スタンドアロンコンテナーの場合は、admin 権限を持つ有効な JAAS ユーザークレデンシャルを使用します。

クライアントで利用可能なオプションを表示するには、以下を入力します。

client --help

Karaf クライアントのヘルプ

Apache Felix Karaf client
  -a [port]     specify the port to connect to
  -h [host]     specify the host to connect to
  -u [user]     specify the user name
  -p [password] specify the password
  --help        shows this help message
  -v            raise verbosity
  -r [attempts] retry connection establishment (up to attempts times)
  -d [delay]    intra-retry delay (defaults to 2 seconds)
  [commands]    commands to run
If no commands are specified, the client will be put in an interactive mode

17.2.2.2. リモートクライアントのデフォルトクレデンシャル

クレデンシャルを指定しなくても、bin/client を使用して Karaf コンテナーにログインできることに驚くかもしれません。これは、リモートクライアントプログラムがデフォルトのクレデンシャルを使用するように事前設定されているためです。クレデンシャルが指定されていない場合、リモートクライアントは自動的に以下のデフォルトクレデンシャルの使用を試みます (順番に) 。

  • デフォルトの SSH キー - デフォルトの Apache Karaf SSH キーを使用してログインを試みます。このログインが正常に行われるようにする設定エントリーは、etc/keys.properties ファイルでデフォルトでコメントアウトされています。
  • デフォルトのユーザ名/パスワードクレデンシャル - ユーザー名とパスワードの組み合わせ admin/admin を使用してログインを試みます。このログインが正常に行われるようにする設定エントリーは、etc/users.properties ファイルでデフォルトでコメントアウトされています。

そのため、users.properties でデフォルトの admin/admin クレデンシャルをアンコメントして、Karaf コンテナーに新しいユーザーを作成する場合は、クレデンシャルを指定せずに bin/client ユーティリティーがログインできます。

重要

セキュリティー上の理由で、Karaf コンテナーが最初にインストールされるときに、Fuse はデフォルトのクレデンシャルを無効にします (コメントアウトして)。ただし、デフォルトのパスワードや SSH 公開鍵を変更せずにこれらのデフォルトクレデンシャルをアンコメントすると、Karaf コンテナにセキュリティーホールが発生します。これは実稼働環境では絶対に行わないでください。クレデンシャルを提供せずに bin/client を使用してコンテナーにログインできる場合、コンテナーには安全ではないため、実稼働環境で修正手順を実行する必要があります。

17.2.2.3. リモートクライアントコンソールからの切断

コマンドを渡すためにリモートクライアントを使用する代わりに、リモートクライアントを使用してリモートコンソールを開いた場合は、リモートクライアントからコネクションを切断する必要があります。リモートクライアントのコンソールから切断するには、logout を入力するか、プロンプトで Ctrl-D を押します。

クライアントが切断され、終了します。

17.2.3. SSH コマンドラインユーティリティーを使用したコンテナーへの接続

17.2.3.1. 概要

また、ssh コマンドラインユーティリティー (UNIX 系オペレーティングシステムで標準のユーティリティー) を使用して Red Hat Fuse コンテナーにログインすることもできます。この認証メカニズムは、公開鍵の暗号化に基づいています (最初にコンテナーにインストールする必要があります)。たとえば、コンテナーが TCP ポート 8101 でリッスンするように設定されている場合、以下のようにログインできます。

ssh -p 8101 jdoe@localhost
重要

現在、キーベースのログインはスタンドアロンコンテナーでのみサポートされており、Fabric コンテナーではサポートされません。

17.2.3.2. 前提条件

キーベースの SSH ログインを使用するには、以下の前提条件を満たす必要があります。

17.2.3.3. デフォルトのキーの場所

ssh コマンドは、デフォルトのキーの場所で秘密鍵を自動的に検索します。キーをデフォルトの場所にインストールすることをお勧めします。これにより、場所を明示的に指定する手間が省かれます。

*NIX オペレーティングシステムでは、RSA 鍵ペアのデフォルトの場所は以下のとおりです。

~/.ssh/id_rsa
~/.ssh/id_rsa.pub

Windows オペレーティングシステムでは、RSA 鍵ペアのデフォルトの場所は以下のとおりです。

C:\Documents and Settings\Username\.ssh\id_rsa
C:\Documents and Settings\Username\.ssh\id_rsa.pub
注記

Red Hat Fuse は RSA 鍵のみをサポートします。DSA 鍵は機能しません

17.2.3.4. 新規の SSH キーペアの作成

ssh-keygen ユーティリティーを使用して RSA 鍵ペアを生成します。新しいコマンドプロンプトを開き、以下のコマンドを入力します。

ssh-keygen -t rsa -b 2048

上記のコマンドは、キー長が 2048 ビットの RSA キーを生成します。次に、キーペアのファイル名を指定するように求められます。

Generating public/private rsa key pair.
Enter file in which to save the key (/Users/Username/.ssh/id_rsa):

Return と入力して、キーペアをデフォルトの場所に保存します。これにより、パスフレーズの入力が求められます。

Enter passphrase (empty for no passphrase):

必要に応じて、ここにパスフレーズを入力するか、Return を 2 回入力して、パスフレーズを指定しないこともできます。

注記

Fabric コンソールコマンドの実行に同じキーペアを使用する場合は、パスフレーズを選択しないことを推奨します。これは、Fabric は暗号化された秘密鍵の使用をサポートしていないためです。

17.2.3.5. コンテナーへの SSH 公開鍵のインストール

Red Hat Fuse コンテナーにログインするときに SSH キーペアを使用するには、INSTALL_DIR/etc/keys.properties ファイルに新しいユーザーエントリーを作成し、コンテナーに SSH 公開鍵をインストールする必要があります。このファイルの各ユーザーエントリーは、以下の形式で 1 行に表示されます。

Username=PublicKey,Role1,Role2,...

たとえば、公開鍵ファイル ~/.ssh/id_rsa.pub に以下の内容があるとします。

ssh-rsa AAAAB3NzaC1kc3MAAACBAP1/U4EddRIpUt9KnC7s5Of2EbdSPO9EAMMeP4C2USZpRV1AIlH7WT2NWPq/xfW6MPbLm1Vs14E7
gB00b/JmYLdrmVClpJ+f6AR7ECLCT7up1/63xhv4O1fnfqimFQ8E+4P208UewwI1VBNaFpEy9nXzrith1yrv8iIDGZ3RSAHHAAAAFQCX
YFCPFSMLzLKSuYKi64QL8Fgc9QAAAnEA9+GghdabPd7LvKtcNrhXuXmUr7v6OuqC+VdMCz0HgmdRWVeOutRZT+ZxBxCBgLRJFnEj6Ewo
FhO3zwkyjMim4TwWeotifI0o4KOuHiuzpnWRbqN/C/ohNWLx+2J6ASQ7zKTxvqhRkImog9/hWuWfBpKLZl6Ae1UlZAFMO/7PSSoAAACB
AKKSU2PFl/qOLxIwmBZPPIcJshVe7bVUpFvyl3BbJDow8rXfskl8wO63OzP/qLmcJM0+JbcRU/53Jj7uyk31drV2qxhIOsLDC9dGCWj4
7Y7TyhPdXh/0dthTRBy6bqGtRPxGa7gJov1xm/UuYYXPIUR/3x9MAZvZ5xvE0kYXO+rx jdoe@doemachine.local

以下のエントリーを 1 行で InstallDir/etc/keys.properties ファイルに追加することで、admin ロールで jdoe ユーザーを作成することができます。

jdoe=AAAAB3NzaC1kc3MAAACBAP1/U4EddRIpUt9KnC7s5Of2EbdSPO9EAMMeP4C2USZpRV1AIlH7WT2NWPq/xfW6MPbLm1Vs14E7
gB00b/JmYLdrmVClpJ+f6AR7ECLCT7up1/63xhv4O1fnfqimFQ8E+4P208UewwI1VBNaFpEy9nXzrith1yrv8iIDGZ3RSAHHAAAAFQCX
YFCPFSMLzLKSuYKi64QL8Fgc9QAAAnEA9+GghdabPd7LvKtcNrhXuXmUr7v6OuqC+VdMCz0HgmdRWVeOutRZT+ZxBxCBgLRJFnEj6Ewo
FhO3zwkyjMim4TwWeotifI0o4KOuHiuzpnWRbqN/C/ohNWLx+2J6ASQ7zKTxvqhRkImog9/hWuWfBpKLZl6Ae1UlZAFMO/7PSSoAAACB
AKKSU2PFl/qOLxIwmBZPPIcJshVe7bVUpFvyl3BbJDow8rXfskl8wO63OzP/qLmcJM0+JbcRU/53Jj7uyk31drV2qxhIOsLDC9dGCWj4
7Y7TyhPdXh/0dthTRBy6bqGtRPxGa7gJov1xm/UuYYXPIUR/3x9MAZvZ5xvE0kYXO+rx,admin
重要

ここで、id_rsa.pub ファイルの内容をすべて挿入しないでください。公開鍵自体を表すシンボルのブロックのみを挿入します。

17.2.3.6. 公開鍵認証のサポートの確認

コンテナーの起動後、以下のように jaas:realms コンソールコマンドを実行して、公開鍵認証がサポートされているかどうかを確認できます。

karaf@root()> jaas:realms
Index │ Realm Name │ Login Module Class Name
──────┼────────────┼─────────────────────────────────────────────────────-
1 │ karaf │ org.apache.karaf.jaas.modules.properties.PropertiesLoginModule
2 │ karaf │ org.apache.karaf.jaas.modules.publickey.PublickeyLoginModule
3 │ karaf │ org.apache.karaf.jaas.modules.audit.FileAuditLoginModule
4 │ karaf │ org.apache.karaf.jaas.modules.audit.LogAuditLoginModule
5 │ karaf │ org.apache.karaf.jaas.modules.audit.EventAdminAuditLoginModule
karaf@root()>

PublickeyLoginModule がインストールされていることがわかります。この設定では、ユーザー名/パスワードのクレデンシャルまたは公開鍵のクレデンシャルを使用してコンテナーにログインできます。

17.2.3.7. ssh ロールの etc/keys.properties への追加

etc/keys.properties で定義された admingroup には、以下の例に示すように ssh ロールが含まれている必要があります。

#
# For security reason, the default auto-signed key is disabled.
# The user guide describes how to generate/update the key.
#
#karaf=AAAAB3NzaC1kc3MAAACBAP1/U4EddRIpUt9KnC7s5Of2EbdSPO9EAMMeP4C2USZpRV1AIlH7WT2NWPq/xfW6MPbLm1Vs14E7gB00b/JmYLdrmVClpJ+f6AR7ECLCT7up1/63xhv4O1fnxqimFQ8E+4P208UewwI1VBNaFpEy9nXzrith1yrv8iIDGZ3RSAHHAAAAFQCXYFCPFSMLzLKSuYKi64QL8Fgc9QAAAIEA9+GghdabPd7LvKtcNrhXuXmUr7v6OuqC+VdMCz0HgmdRWVeOutRZT+ZxBxCBgLRJFnEj6EwoFhO3zwkyjMim4TwWeotUfI0o4KOuHiuzpnWRbqN/C/ohNWLx+2J6ASQ7zKTxvqhRkImog9/hWuWfBpKLZl6Ae1UlZAFMO/7PSSoAAACBAKKSU2PFl/qOLxIwmBZPPIcJshVe7bVUpFvyl3BbJDow8rXfskl8wO63OzP/qLmcJM0+JbcRU/53JjTuyk31drV2qxhIOsLDC9dGCWj47Y7TyhPdXh/0dthTRBy6bqGtRPxGa7gJov1xm/UuYYXPIUR/3x9MAZvZ5xvE0kYXO+rx,_g_:admingroup
_g_\:admingroup = group,admin,manager,viewer,systembundles,ssh

ssh ロールが admingroup の定義に含まれていない場合は、etc/keys.properties を編集し、ssh ロールを追加する必要があります。

17.2.3.8. キーベースの SSH を使用したログイン

これで、キーベースの SSH ユーティリティーを使用してコンテナーにログインできるようになりました。以下に例を示します。

$ ssh -p 8101 jdoe@localhost
____          _   _   _       _     _____
|  _ \ ___  __| | | | | | __ _| |_  |  ___|   _ ___  ___
| |_) / _ \/ _` | | |_| |/ _` | __| | |_ | | | / __|/ _ \
|  _ <  __/ (_| | |  _  | (_| | |_  |  _|| |_| \__ \  __/
|_| \_\___|\__,_| |_| |_|\__,_|\__| |_|   \__,_|___/___|

  Fuse (7.x.x.fuse-xxxxxx-redhat-xxxxx)
  http://www.redhat.com/products/jbossenterprisemiddleware/fuse/

Hit '<tab>' for a list of available commands
and '[cmd] --help' for help on a specific command.

Open a browser to http://localhost:8181/hawtio to access the management console

Hit '<ctrl-d>' or 'shutdown' to shutdown Red Hat Fuse.

karaf@root()>
注記

暗号化された秘密鍵を使用している場合は、ssh ユーティリティーにより、パスフレーズの入力が求められます。

17.3. リモートコンテナーの停止

ssh:ssh コマンドまたはリモートクライアントを使用してリモートコンソールに接続している場合は、osgi:shutdown コマンドを使用してリモートインスタンスを停止できます。

注記

リモートコンソールで Ctrl+D を押すと、リモート接続を終了して、ローカルシェルに戻ります。

第18章 Maven でのビルド

概要

Maven は、 Apache Maven プロジェクトで利用可能なオープンソースのビルドシステムです。本章では、基本的な Maven の概念を説明し、Red Hat Fuse と連携するように Maven を設定する方法を説明します。原則では、あらゆるビルドシステムを使用して OSGi バンドルをビルドできます。しかし、Red Hat Fuse によって適切にサポートされるため、Maven の使用が強く推奨されます。

18.1. Maven ディレクトリー構造

18.1.1. 概要

Maven ビルドシステムの最も重要な原則の 1 つは、Maven プロジェクト内のすべてのファイルに標準的な場所があることです。この原則にはいくつかの利点があります。利点の 1 つは、Maven プロジェクトのディレクトリーレイアウトは通常同じで、プロジェクトのファイルを簡単に検索できることです。もう 1 つの利点は、Maven と統合されたさまざまなツールでは、ほとんど初期設定が不要であることです。たとえば、Java コンパイラーは、src/main/java 下のソースファイルをすべてコンパイルし、結果を target/classes に配置する必要があることを認識しています。

18.1.2. 標準ディレクトリーレイアウト

例18.1「標準 Maven ディレクトリーレイアウト」 は、OSGi バンドルプロジェクトのビルドに関連する標準の Maven ディレクトリーレイアウトの要素を示しています。さらに、Blueprint 設定ファイル (Maven で定義されない) の標準の場所も示されています。

例18.1 標準 Maven ディレクトリーレイアウト

ProjectDir/
    pom.xml
    src/
        main/
            java/
                ...
            resources/
                META-INF/

                OSGI-INF/
                    blueprint/
                        *.xml
        test/
            java/
            resources/
    target/
        ...
注記

標準のディレクトリーレイアウトを上書きすることは可能ですが、これは Maven では推奨されません

18.1.3. pom.xml ファイル

pom.xml ファイルは現在のプロジェクトのプロジェクトオブジェクトモデル (POM) です。これには、現在のプロジェクトのビルド方法に関する完全な説明が含まれています。pom.xml ファイルは完全に自己完結型にすることができますが、これは頻繁に (特に複雑な Maven プロジェクトの場合) 親 POM ファイルから設定をインポートできます。

プロジェクトをビルドすると、生成された JAR ファイルの以下の場所に pom.xml ファイルのコピーが自動的に組み込まれます。

META-INF/maven/groupId/artifactId/pom.xml

18.1.4. src ディレクトリーおよび target ディレクトリー

src/ ディレクトリーには、プロジェクトの開発中に作業するすべてのコードおよびリソースファイルが含まれます。

target/ ディレクトリーには、ビルドの結果 (通常は JAR ファイル) と、ビルド中に生成されたすべての中間ファイルが含まれます。たとえば、ビルドの実行後、target/classes/ ディレクトリーにはリソースファイルのコピーとコンパイルした Java クラスが含まれます。

18.1.5. main ディレクトリーおよび test ディレクトリー

src/main/ ディレクトリーには、アーティファクトのビルドに必要なすべてのコードおよびリソースが含まれます。

src/test/ ディレクトリーには、コンパイルされたアーティファクトに対して単体テストを実行するためのすべてのコードおよびリソースが含まれます。

18.1.6. java ディレクトリー

java/ サブディレクトリーには、標準の Java ディレクトリーレイアウト (ディレクトリーパス名が . の代わりに / で Java パッケージ名をミラーリングする) を持つ Java ソースコード (*.java ファイル) が含まれます。src/main/java/ ディレクトリーにはバンドルソースコードが含まれ、src/test/java/ ディレクトリーには単体テストのソースコードが含まれます。

18.1.7. resources ディレクトリー

バンドルに含める設定ファイル、データファイル、または Java プロパティーがある場合は、これらを src/main/resources/ ディレクトリー下に配置する必要があります。src/main/resources/ 下のファイルおよびディレクトリーは、Maven ビルドプロセスによって生成される JAR ファイルのルートにコピーされます。

src/test/resources/ 下のファイルは、テストフェーズ中にのみ使用され、生成された JAR ファイルにコピーされません

18.1.8. Blueprint コンテナー

OSGi R4.2 は Blueprint コンテナーを定義します。Red Hat Fuse には Blueprint コンテナーのサポートが組み込まれています。これは、プロジェクト内に OSGI-INF/blueprint/*.xml という Blueprint 設定ファイルを含むだけで有効にできます。Blueprint コンテナーの詳細は、12章OSGi サービス を参照してください。

18.2. Apache Karaf の BOM ファイル

Maven BOM (Bill of Materials) ファイルの目的は、正常に動作する Maven 依存関係バージョンのセットを提供し、各 Maven アーティファクトに対して個別にバージョンを定義する必要をなくすことです。

Apache Karaf の Fuse BOM には以下の利点があります。

  • Maven 依存関係のバージョンを定義するため、依存関係を POM に追加するときにバージョンを指定する必要がありません。
  • 特定バージョンの Fuse に対して完全にテストされ、完全にサポートする依存関係のセットを定義します。
  • Fuse のアップグレードを簡素化します。
重要

Fuse BOM によって定義される依存関係のセットのみが Red Hat によってサポートされます。

Maven プロジェクトに Maven BOM ファイルを組み込むには、以下の例のように、プロジェクトの pom.xml ファイル (または親 POM ファイル内の) dependencyManagement 要素を指定します。

<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<project ...>
  ...
  <properties>
    <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>

    <!-- configure the versions you want to use here -->
    <fuse.version>7.9.0.fuse-sb2-790065-redhat-00001</fuse.version>

  </properties>

  <dependencyManagement>
    <dependencies>
      <dependency>
        <groupId>org.jboss.redhat-fuse</groupId>
        <artifactId>fuse-karaf-bom</artifactId>
        <version>${fuse.version}</version>
        <type>pom</type>
        <scope>import</scope>
      </dependency>
    </dependencies>
  </dependencyManagement>
  ...
</project>
注記

org.jboss.redhat-fuse BOM は Fuse 7 の新機能で、BOM のバージョン管理を簡素化するように設計されています。ただし、Fuse クイックスタートと Maven アーキタイプは、まだ新しいスタイルの BOM を使用するようにリファクタリングされていないため、古いスタイルの BOM を使用しています。両方の BOM が適切であるため、どちらも Maven プロジェクトで使用できます。今後の Fuse リリースでは、クイックスタートと Maven アーキタイプが新しい BOM を使用するようにリファクタリングされます。

依存関係管理のメカニズムを使用して BOM を指定した後、アーティファクトのバージョンを指定しなくても、Maven 依存関係を POM に追加できるようになります。たとえば、camel-velocity コンポーネントの依存関係を追加するには、以下の XML フラグメントを POM の dependencies 要素に追加します。

<dependency>
  <groupId>org.apache.camel</groupId>
  <artifactId>camel-velocity</artifactId>
</dependency>

この依存関係の定義では、version 要素が省略されることに注意してください。

第19章 Maven Indexer プラグイン

Maven Indexer プラグインは、Maven プラグインがアーティファクトを Maven Central ですばやく検索できるようにするために必要です。

Maven Indexer プラグインをデプロイするには、以下のコマンドを使用します。

前提条件

Maven Indexer プラグインをデプロイする前に、『Installing on Apache Karaf』の「Preparing to Use Maven」の手順に従ったことを確認してください。

Maven Indexer プラグインのデプロイ

  1. Karaf コンソールに移動し、以下のコマンドを入力し、Maven Indexer プラグインをインストールします。

    features:install hawtio-maven-indexer
  2. 以下のコマンドを入力して Maven Indexer プラグインを設定します。

    config:edit io.hawt.maven.indexer
    config:proplist
    config:propset repositories 'https://maven.oracle.com'
    config:proplist
    config:update
  3. Maven Indexer プラグインがデプロイされるまで待ちます。これには数分かかる場合があります。ログタブに以下のようなメッセージが表示されるの確認します。

    maven indexer log

Maven Indexer プラグインがデプロイされたら、次のコマンドを使用して、Maven Indexer プラグイン設定に外部 Maven リポジトリーを追加します。

config:edit io.hawt.maven.indexer
config:proplist
config:propset repositories external repository
config:proplist
config:update

19.1. ログ

Apache Karaf は、動的および強力なロギングシステムを提供します。

以下をサポートします。

  • OSGi Log Service
  • Apache Log4j v1 および v2 フレームワーク
  • Apache Commons Logging フレームワーク
  • Logback フレームワーク
  • SLF4J フレームワーク
  • ネイティブ Java Util Logging フレームワーク

これは、アプリケーションが任意のロギングフレームワークを使用できることを意味し、Apache Karaf は中央ログシステムを使用してロガー、アペンダーなどを管理します。

19.1.1. 設定ファイル

初期ログ設定は etc/org.ops4j.pax.logging.cfg からロードされます。

このファイルは、標準の Log4j2 設定ファイルです。

さまざまな log4j2 要素が見つかります。

  • ロガー
  • アペンダー
  • レイアウト

独自の初期設定をファイルに直接追加できます。

デフォルト設定は以下のとおりです。

#
#  Copyright 2005-2018 Red Hat, Inc.
#
#  Red Hat licenses this file to you under the Apache License, version
#  2.0 (the "License"); you may not use this file except in compliance
#  with the License.  You may obtain a copy of the License at
#
#     http://www.apache.org/licenses/LICENSE-2.0
#
#  Unless required by applicable law or agreed to in writing, software
#  distributed under the License is distributed on an "AS IS" BASIS,
#  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
#  implied.  See the License for the specific language governing
#  permissions and limitations under the License.
#

#
# Internal Log4j2 configuration
#
log4j2.status = WARN
log4j2.verbose = false
log4j2.dest = out

#
# Common pattern layouts for appenders defined as reusable properties
# See https://logging.apache.org/log4j/2.x/manual/layouts.html#PatternLayout
# references will be replaced by felix.fileinstall
#
log4j2.pattern = %d{DEFAULT} | %-5.5p | %-20.20t | %-32.32c{1.} | %X{bundle.id} - %X{bundle.name} - %X{bundle.version} | %m%n
#log4j2.pattern = %d{DEFAULT} %-5.5p {%t} [%C.%M()] (%F:%L) : %m%n

#
# Appenders configuration
#

# JDBC Appender
log4j2.appender.jdbc.type = JDBC
log4j2.appender.jdbc.name = JdbcAppender
log4j2.appender.jdbc.tableName = EVENTS
log4j2.appender.jdbc.cs.type = DataSource
log4j2.appender.jdbc.cs.lazy = true
log4j2.appender.jdbc.cs.jndiName = osgi:service/jdbc/logdb
log4j2.appender.jdbc.c1.type = Column
log4j2.appender.jdbc.c1.name = DATE
log4j2.appender.jdbc.c1.isEventTimestamp = true
log4j2.appender.jdbc.c2.type = Column
log4j2.appender.jdbc.c2.name = LEVEL
log4j2.appender.jdbc.c2.pattern = %level
log4j2.appender.jdbc.c2.isUnicode = false
log4j2.appender.jdbc.c3.type = Column
log4j2.appender.jdbc.c3.name = SOURCE
log4j2.appender.jdbc.c3.pattern = %logger
log4j2.appender.jdbc.c3.isUnicode = false
log4j2.appender.jdbc.c4.type = Column
log4j2.appender.jdbc.c4.name = THREAD_ID
log4j2.appender.jdbc.c4.pattern = %thread
log4j2.appender.jdbc.c4.isUnicode = false
log4j2.appender.jdbc.c5.type = Column
log4j2.appender.jdbc.c5.name = MESSAGE
log4j2.appender.jdbc.c5.pattern = %message
log4j2.appender.jdbc.c5.isUnicode = false


# Console appender not used by default (see log4j2.rootLogger.appenderRefs)
log4j2.appender.console.type = Console
log4j2.appender.console.name = Console
log4j2.appender.console.layout.type = PatternLayout
log4j2.appender.console.layout.pattern = ${log4j2.pattern}

# Rolling file appender
log4j2.appender.rolling.type = RollingRandomAccessFile
log4j2.appender.rolling.name = RollingFile
log4j2.appender.rolling.fileName = ${karaf.data}/log/fuse.log
log4j2.appender.rolling.filePattern = ${karaf.data}/log/fuse-%i.log.gz
# uncomment to not force a disk flush
#log4j2.appender.rolling.immediateFlush = false
log4j2.appender.rolling.append = true
log4j2.appender.rolling.layout.type = PatternLayout
log4j2.appender.rolling.layout.pattern = ${log4j2.pattern}
log4j2.appender.rolling.policies.type = Policies
log4j2.appender.rolling.policies.size.type = SizeBasedTriggeringPolicy
log4j2.appender.rolling.policies.size.size = 16MB
log4j2.appender.rolling.strategy.type = DefaultRolloverStrategy
log4j2.appender.rolling.strategy.max = 20

# Audit file appender
log4j2.appender.audit.type = RollingRandomAccessFile
log4j2.appender.audit.name = AuditRollingFile
log4j2.appender.audit.fileName = ${karaf.data}/security/audit.log
log4j2.appender.audit.filePattern = ${karaf.data}/security/audit.log.%i
log4j2.appender.audit.append = true
log4j2.appender.audit.layout.type = PatternLayout
log4j2.appender.audit.layout.pattern = ${log4j2.pattern}
log4j2.appender.audit.policies.type = Policies
log4j2.appender.audit.policies.size.type = SizeBasedTriggeringPolicy
log4j2.appender.audit.policies.size.size = 8MB

# OSGi appender
log4j2.appender.osgi.type = PaxOsgi
log4j2.appender.osgi.name = PaxOsgi
log4j2.appender.osgi.filter = *

#
# Loggers configuration
#

# Root logger
log4j2.rootLogger.level = INFO
log4j2.rootLogger.appenderRef.RollingFile.ref = RollingFile
log4j2.rootLogger.appenderRef.PaxOsgi.ref = PaxOsgi
log4j2.rootLogger.appenderRef.Console.ref = Console
log4j2.rootLogger.appenderRef.Console.filter.threshold.type = ThresholdFilter
log4j2.rootLogger.appenderRef.Console.filter.threshold.level = ${karaf.log.console:-OFF}
#log4j2.rootLogger.appenderRef.Sift.ref = Routing

# Spifly logger
log4j2.logger.spifly.name = org.apache.aries.spifly
log4j2.logger.spifly.level = WARN

# Security audit logger
log4j2.logger.audit.name = org.apache.karaf.jaas.modules.audit
log4j2.logger.audit.level = INFO
log4j2.logger.audit.additivity = false
log4j2.logger.audit.appenderRef.AuditRollingFile.ref = AuditRollingFile

# help with identification of maven-related problems with pax-url-aether
#log4j2.logger.aether.name = shaded.org.eclipse.aether
#log4j2.logger.aether.level = TRACE
#log4j2.logger.http-headers.name = shaded.org.apache.http.headers
#log4j2.logger.http-headers.level = DEBUG
#log4j2.logger.maven.name = org.ops4j.pax.url.mvn
#log4j2.logger.maven.level = TRACE

デフォルト設定では、out ファイルアペンダーを使用して、INFO ログレベルで ROOT ロガーを定義します。ログレベルを Log4j2 の有効な値に変更できます。最も詳細なログレベルの順に TRACE、DEBUG、INFO、ERROR、FATAL となり、これらを指定できます。

OSGi アペンダー
osgi:* アペンダーは、ログメッセージを OSGi Log Service に送信する特別なアペンダーです。
stdout アペンダー
stdout コンソールアペンダーは事前設定されていますが、デフォルトでは有効になっていません。このアペンダーを使用すると、標準出力に直接ログメッセージを表示できます。Apache Karaf をサーバーモード (コンソールなし) で実行する予定の場合に有用です。

有効にするには、stdout アペンダーを rootLogger に追加する必要があります。

log4j2.rootLogger=INFO, out, stdout, osgi:*
out アペンダー
out アペンダーは、デフォルトのアペンダーです。これは、10 個の 1MB ログファイルを維持およびローテーションするローリングファイルアペンーダです。ログファイルはデフォルトで data/log/fuse.log にあります。
sift アペンダー
sift アペンダーは、デフォルトでは有効になっていません。このアペンダーを使用すると、デプロイされたバンドルごとに 1 つのログファイルを指定できます。デフォルトでは、ログファイルの名前の形式は、バンドルのシンボリック名 (data/log フォルダーの) を使用します。このファイルは実行時に編集できます。Apache Karaf はファイルをリロードし、変更が有効になります。Apache Karaf を再起動する必要はありません。別の設定ファイルは Apache Karaf により使用されます(etc/org.apache.karaf.log.cfg)。このファイルは、ログコマンドで使用されるログサービスを設定します (後で参照)。
jdbc アペンダー
jdbc アペンダーには lazy フラグがあり、true (有効) で、データソースが利用できない場合は、ロギングはデータベースに追加されません。ただし、jndi、データソース、またはコネクションが復活すると、ロギングが再起動します。
log4j2.appender.jdbc.cs.lazy = true
重要

ロギングメッセージが失われないようにするには、緊急アペンダーを設定することをお勧めします。

19.1.2. コマンド

Apache Karaf は、etc/org.ops4j.pax.logging.cfg ファイルを変更する代わりに、ログ設定を動的に変更してログの内容を確認できる一連のコマンドを提供します。

19.1.2.1. log:clear

log:clear コマンドはログエントリーを消去します。

19.1.2.2. log:display

log:display コマンドは、ログエントリーを表示します。

デフォルトでは、rootLogger のログエントリーが表示されます。

karaf@root()> log:display
2015-07-01 19:12:46,208 | INFO  | FelixStartLevel  | SecurityUtils                    | 16 - org.apache.sshd.core - 0.12.0 | BouncyCastle not registered, using the default JCE provider
2015-07-01 19:12:47,368 | INFO  | FelixStartLevel  | core                             | 68 - org.apache.aries.jmx.core - 1.1.1 | Starting JMX OSGi agent

logger 引数を使用して、特定のロガーからログエントリーを表示することもできます。

karaf@root()> log:display ssh
2015-07-01 19:12:46,208 | INFO  | FelixStartLevel  | SecurityUtils                    | 16 - org.apache.sshd.core - 0.12.0 | BouncyCastle not registered, using the default JCE provider

デフォルトでは、すべてのログエントリーが表示されます。Apache Karaf コンテナーが長時間稼働していると、非常に長くなる場合があります。-n オプションを使用して、表示するエントリー数を制限することができます。

karaf@root()> log:display -n 5
2015-07-01 06:53:24,143 | INFO  | JMX OSGi Agent   | core                             | 68 - org.apache.aries.jmx.core - 1.1.1 | Registering org.osgi.jmx.framework.BundleStateMBean to MBeanServer com.sun.jmx.mbeanserver.JmxMBeanServer@27cc75cb with name osgi.core:type=bundleState,version=1.7,framework=org.apache.felix.framework,uuid=5335370f-9dee-449f-9b1c-cabe74432ed1
2015-07-01 06:53:24,150 | INFO  | JMX OSGi Agent   | core                             | 68 - org.apache.aries.jmx.core - 1.1.1 | Registering org.osgi.jmx.framework.PackageStateMBean to MBeanServer com.sun.jmx.mbeanserver.JmxMBeanServer@27cc75cb with name osgi.core:type=packageState,version=1.5,framework=org.apache.felix.framework,uuid=5335370f-9dee-449f-9b1c-cabe74432ed1
2015-07-01 06:53:24,150 | INFO  | JMX OSGi Agent   | core                             | 68 - org.apache.aries.jmx.core - 1.1.1 | Registering org.osgi.jmx.framework.ServiceStateMBean to MBeanServer com.sun.jmx.mbeanserver.JmxMBeanServer@27cc75cb with name osgi.core:type=serviceState,version=1.7,framework=org.apache.felix.framework,uuid=5335370f-9dee-449f-9b1c-cabe74432ed1
2015-07-01 06:53:24,152 | INFO  | JMX OSGi Agent   | core                             | 68 - org.apache.aries.jmx.core - 1.1.1 | Registering org.osgi.jmx.framework.wiring.BundleWiringStateMBean to MBeanServer com.sun.jmx.mbeanserver.JmxMBeanServer@27cc75cb with name osgi.core:type=wiringState,version=1.1,framework=org.apache.felix.framework,uuid=5335370f-9dee-449f-9b1c-cabe74432ed1
2015-07-01 06:53:24,501 | INFO  | FelixStartLevel  | RegionsPersistenceImpl           | 78 - org.apache.karaf.region.persist - 4.0.0 | Loading region digraph persistence

etc/org.apache.karaf.log.cfg ファイルの size プロパティーを使用すると、保存され保持されるエントリーの数を制限することもできます。

#
# The number of log statements to be displayed using log:display. It also defines the number
# of lines searched for exceptions using log:display exception. You can override this value
# at runtime using -n in log:display.
#
size = 500

デフォルトでは、各ログレベルは異なる色で表示されます。ERROR/FATAL は赤、DEBUG は紫、INFO は青緑などです。--no-color オプションを使用して色付けを無効にすることができます。

ログエントリーの形式パターンは、etc/org.ops4j.pax.logging.cfg ファイルに定義された変換パターンを使用しません。デフォルトでは、etc/org.apache.karaf.log.cfg で定義される pattern プロパティーを使用します。

#
# The pattern used to format the log statement when using log:display. This pattern is according
# to the log4j2 layout. You can override this parameter at runtime using log:display with -p.
#
pattern = %d{ISO8601} | %-5.5p | %-16.16t | %-32.32c{1} | %X{bundle.id} - %X{bundle.name} - %X{bundle.version} | %m%n

-p オプションを使用して、パターンを動的に変更することもできます (1 回の実行)。

karaf@root()> log:display -p "\%d - \%c - \%m\%n"
2015-07-01 07:01:58,007 - org.apache.sshd.common.util.SecurityUtils - BouncyCastle not registered, using the default JCE provider
2015-07-01 07:01:58,725 - org.apache.aries.jmx.core - Starting JMX OSGi agent
2015-07-01 07:01:58,744 - org.apache.aries.jmx.core - Registering MBean with ObjectName [osgi.compendium:service=cm,version=1.3,framework=org.apache.felix.framework,uuid=6361fc65-8df4-4886-b0a6-479df2d61c83] for service with service.id [13]
2015-07-01 07:01:58,747 - org.apache.aries.jmx.core - Registering org.osgi.jmx.service.cm.ConfigurationAdminMBean to MBeanServer com.sun.jmx.mbeanserver.JmxMBeanServer@27cc75cb with name osgi.compendium:service=cm,version=1.3,framework=org.apache.felix.framework,uuid=6361fc65-8df4-4886-b0a6-479df2d61c83

このパターンは、通常の Log4j2 パターンで、日付の %d、クラスの %c、ログメッセージの %m などのキーワードを使用できます。

19.1.2.3. log:exception-display

log:exception-display コマンドは、最後に発生した例外を表示します。

log:display コマンドの場合、log:exception-display コマンドはデフォルトで rootLogger を使用しますが、logger 引数でロガーを指定できます。

19.1.2.4. log:get

log:get コマンドは、ロガーの現在のログレベルを表示します。

デフォルトでは、表示されるログレベルはルートロガーのログレベルです。

karaf@root()> log:get
Logger                              │ Level
────────────────────────────────────┼──────
ROOT                                │ INFO
org.apache.aries.spifly             │ WARN
org.apache.karaf.jaas.modules.audit │ INFO
org.apache.sshd                     │ INFO

logger 引数を使用して、特定のロガーを指定できます。

karaf@root()> log:get ssh
INFO

logger 引数は、ALL キーワードを受け入れて、(リストとして) すべてのロガーのログレベルを表示します。

たとえば、etc/org.ops4j.pax.logging.cfgファイルに独自のロガーを次のように定義します。

log4j2.logger.my.name = MyLogger
log4j2.logger.my.level = DEBUG

対応するログレベルのロガーのリストが表示されます。

karaf@root()> log:get ALL
Logger                              │ Level
────────────────────────────────────┼──────
MyLogger                            │ DEBUG
ROOT                                │ INFO
org.apache.aries.spifly             │ WARN
org.apache.karaf.jaas.modules.audit │ INFO
org.apache.sshd                     │ INFO

log:list コマンドは、log:get ALL のエイリアスです。

19.1.2.5. log:log

log:log コマンドを使用すると、ログにメッセージを手動で追加できます。Apache Karaf スクリプトを作成する場合に有用です。

karaf@root()> log:log "Hello World"
karaf@root()> log:display
12:55:21.706 INFO [pipe-log:log "Hello World"] Hello World

デフォルトでは、ログレベルは INFO ですが、-l オプションを使用して別のログレベルを指定できます。

karaf@root()> log:clear
karaf@root()> log:log -l ERROR "Hello World"
karaf@root()> log:display
12:55:41.460 ERROR [pipe-log:log "Hello World"] Hello World

19.1.2.6. log:set

log:set コマンドは、ロガーのログレベルを設定します。

デフォルトでは、rootLogger のログレベルが変更されます。

karaf@root()> log:set DEBUG
karaf@root()> log:get
Logger                              │ Level
────────────────────────────────────┼──────
ROOT                                │ DEBUG
...

level の後に logger 引数を使用して、特定のロガーを指定できます。

karaf@root()> log:set INFO my.logger
karaf@root()> log:get my.logger
Logger    | Level
-----------------
my.logger | INFO

level 引数は TRACE、DEBUG、INFO、WARN、ERROR、FATAL のいずれかの Log4j2 ログレベルを受け入れます。

また、特殊な DEFAULT キーワードも受け入れます。

DEFAULT キーワードの目的は、ロガーの親のレベルを使用するために (ロガーは階層的です)、ロガーの現在のレベルを削除します (レベルのみが削除され、アペンダーなどの他のプロパティーは削除されません)。

たとえば、以下のロガー (etc/org.ops4j.pax.logging.cfg ファイルの) を定義します。

rootLogger=INFO,out,osgi:*
my.logger=INFO,appender1
my.logger.custom=DEBUG,appender2

my.logger.custom ロガーのレベルを変更することができます。

karaf@root()> log:set INFO my.logger.custom

以下のようになります。

rootLogger=INFO,out,osgi:*
my.logger=INFO,appender1
my.logger.custom=INFO,appender2

my.logger.custom ロガーで DEFAULT キーワードを使用して、レベルを削除できます。

karaf@root()> log:set DEFAULT my.logger.custom

以下のようになります。

rootLogger=INFO,out,osgi:*
my.logger=INFO,appender1
my.logger.custom=appender2

つまり、実行時に my.logger.custom ロガーは親 my.logger のレベルを使用するため、INFO となります。

ここで、my.logger ロガーで DEFAULT キーワードを使用するとします。

karaf@root()> log:set DEFAULT my.logger

以下のようになります。

rootLogger=INFO,out,osgi:*
my.logger=appender1
my.logger.custom=appender2

そのため、my.logger.custommy.logger はいずれも親 rootLogger のログレベルを使用します。

rootLogger で DEFAULT キーワードを使用することはできず、親はありません。

19.1.2.7. log:tail

log:taillog:display と同じですが、ログエントリーが継続的に表示されます。

log:display コマンドと同じオプションと引数を使用できます。

デフォルトでは、rootLogger からのエントリーが表示されます。

karaf@root()> log:tail
2015-07-01 07:40:28,152 | INFO  | FelixStartLevel  | SecurityUtils                    | 16 - org.apache.sshd.core - 0.9.0 | BouncyCastle not registered, using the default JCE provider
2015-07-01 07:40:28,909 | INFO  | FelixStartLevel  | core                             | 68 - org.apache.aries.jmx.core - 1.1.1 | Starting JMX OSGi agent
2015-07-01 07:40:28,928 | INFO  | FelixStartLevel  | core                             | 68 - org.apache.aries.jmx.core - 1.1.1 | Registering MBean with ObjectName [osgi.compendium:service=cm,version=1.3,framework=org.apache.felix.framework,uuid=b44a44b7-41cd-498f-936d-3b12d7aafa7b] for service with service.id [13]
2015-07-01 07:40:28,936 | INFO  | JMX OSGi Agent   | core                             | 68 - org.apache.aries.jmx.core - 1.1.1 | Registering org.osgi.jmx.service.cm.ConfigurationAdminMBean to MBeanServer com.sun.jmx.mbeanserver.JmxMBeanServer@27cc75cb with name osgi.compendium:service=cm,version=1.3,framework=org.apache.felix.framework,uuid=b44a44b7-41cd-498f-936d-3b12d7aafa7b

log:tail コマンドから終了するには、CTRL-C を入力します。

19.1.3. JMX LogMBean

log:* コマンドで実行可能なすべてのアクションは、LogMBean を使用して実行できます。

LogMBean オブジェクト名は org.apache.karaf:type=log,name=* です。

19.1.3.1. 属性

  • Level 属性は、ROOT ロガーのレベルです。

19.1.3.2. 操作

  • getLevel(logger) を使用して特定のロガーのログレベルを取得します。この操作は ALL キーワードをサポートするため、各ロガーのレベルを持つ Map を返します。
  • setLevel(level, logger) を使用して特定のロガーのログレベルを設定します。この操作は、log:set コマンドの DEFAULT キーワードをサポートします。

19.1.4. 詳細設定

19.1.4.1. フィルター

アペンダーにフィルターを適用できます。フィルターは各ログイベントを評価し、ログに送信するかどうかを決定します。

Log4j2 はすぐに使用できるフィルターを提供します。

注記

包括的なビューについては、Log4J サイトの「Filters」を参照してください。

19.1.4.2. ネストされたアペンダー

ネストされたアペンダーは、特別な種類のアペンダーで、「内部」の別のアペンダーを使用します。これにより、アペンダーのチェーン間にある種の「ルーティング」を作成できます。

最もよく使われる「ネスト準拠」アペンダーは次のとおりです。

  • AsyncAppender (org.apache.log4j2.AsyncAppender) はイベントを非同期にログに記録します。このアペンダーはイベントを収集し、それにアタッチされているすべてのアペンダーにそれらをディスパッチします。
  • RewriteAppender (org.apache.log4j2.rewrite.RewriteAppender) は、ログイベントを書き直した後、ログイベントを別のアペンダーに転送します。

このアペンダーは、アペンダー定義で appenders プロパティーを受け入れます。

log4j2.appender.[appender-name].appenders=[comma-separated-list-of-appender-names]

たとえば、async という名前の AsyncAppender を作成し、ログイベントを JMS アペンダーに非同期にディスパッチできます。

log4j2.appender.async=org.apache.log4j2.AsyncAppender
log4j2.appender.async.appenders=jms

log4j2.appender.jms=org.apache.log4j2.net.JMSAppender
...

19.1.4.3. エラーハンドラー

アペンダーは失敗する場合があります。たとえば、RollingFileAppender はファイルシステムへの書き込みを試みてもファイルシステムが満杯であったり、JMS アペンダーがメッセージを送信しようとしても JMS ブローカーは利用できない場合などです。

ロギングは重要なので、ログアペンダーが失敗したかどうかを知ることが重要です。

各ログアペンダーはエラー処理をエラーハンドラーに委譲できます。これは、アペンダーエラーに対応できます。

  • FailoverAppender (org.apache.log4j2.varia.FailoverAppender) を使用すると、プライマリーアペンダーが失敗した場合にセカンダリーアペンダーを引き継ぐことができます。エラーメッセージが System.err で出力され、セカンダリーアペンダーのログに記録されます。
注記

FailoverAppender の詳細は、Log4j2 の Apppender ページ を参照してください。

アペンダー定義自体で errorhandler プロパティーを使用して、各アペンダーに使用するエラーハンドラーを定義できます。

log4j2.appender.[appender-name].errorhandler=[error-handler-class]
log4j2.appender.[appender-name].errorhandler.root-ref=[true|false]
log4j2.appender.[appender-name].errorhandler.logger-ref=[logger-ref]
log4j2.appender.[appender-name].errorhandler.appender-ref=[appender-ref]

19.1.4.4. OSGi 固有の MDC 属性

routing アペンダーは、MDC (Mapped Diagnostic Context) 属性に基づいてログイベントの分割を可能にする OSGi 指向アペンダーです。

MDC では、ログイベントのさまざまなソースを区別できます。

routing アペンダーは、デフォルトで OSGi 指向の MDC 属性を提供します。

  • bundle.id はバンドル ID です。
  • bundle.name はバンドルのシンボリック名です。
  • bundle.version はバンドルバージョンです。

これらの MDC プロパティーを使用して、バンドルごとにログファイルを作成できます。

log4j2.appender.routing.type = Routing
log4j2.appender.routing.name = Routing
log4j2.appender.routing.routes.type = Routes
log4j2.appender.routing.routes.pattern = $$\\{ctx:bundle.name\\}
log4j2.appender.routing.routes.bundle.type = Route
log4j2.appender.routing.routes.bundle.appender.type = RollingRandomAccessFile
log4j2.appender.routing.routes.bundle.appender.name = Bundle-$\\{ctx:bundle.name\}
log4j2.appender.routing.routes.bundle.appender.fileName = ${karaf.data}/log/bundle-$\\{ctx:bundle.name\\}.log
log4j2.appender.routing.routes.bundle.appender.filePattern = ${karaf.data}/log/bundle-$\\{ctx:bundle.name\\}.log.%d{yyyy-MM-dd}
log4j2.appender.routing.routes.bundle.appender.append = true
log4j2.appender.routing.routes.bundle.appender.layout.type = PatternLayout
log4j2.appender.routing.routes.bundle.appender.policies.type = Policies
log4j2.appender.routing.routes.bundle.appender.policies.time.type = TimeBasedTriggeringPolicy
log4j2.appender.routing.routes.bundle.appender.strategy.type = DefaultRolloverStrategy
log4j2.appender.routing.routes.bundle.appender.strategy.max = 31

log4j2.rootLogger.appenderRef.Routing.ref = Routing

19.1.4.5. OSGi スタックトレースレンダラーの拡張

デフォルトでは、Apache Karaf は特別なスタックトレースレンダラーを提供し、OSGi 固有の情報をいくつか追加します。

スタックトレースでは、例外をスローするクラスに加えて、各スタックトレース行の末尾にある [id:name:version] パターンを見つけることができます。

  • id はバンドル ID です。
  • name はバンドル名です。
  • version はバンドルバージョンです。

問題の原因を診断するのに非常に役立ちます。

たとえば、以下の IllegalArgumentException スタックトレースでは、例外のソースに関する OSGi の詳細を確認できます。

java.lang.IllegalArgumentException: Command not found:  *:foo
	at org.apache.felix.gogo.runtime.shell.Closure.execute(Closure.java:225)[21:org.apache.karaf.shell.console:4.0.0]
	at org.apache.felix.gogo.runtime.shell.Closure.executeStatement(Closure.java:162)[21:org.apache.karaf.shell.console:4.0.0]
	at org.apache.felix.gogo.runtime.shell.Pipe.run(Pipe.java:101)[21:org.apache.karaf.shell.console:4.0.0]
	at org.apache.felix.gogo.runtime.shell.Closure.execute(Closure.java:79)[21:org.apache.karaf.shell.console:4.0.0]
	at org.apache.felix.gogo.runtime.shell.CommandSessionImpl.execute(CommandSessionImpl.java:71)[21:org.apache.karaf.shell.console:4.0.0]
	at org.apache.karaf.shell.console.jline.Console.run(Console.java:169)[21:org.apache.karaf.shell.console:4.0.0]
	at java.lang.Thread.run(Thread.java:637)[:1.7.0_21]

19.1.4.6. カスタムアペンダー

Apache Karaf では、独自のアペンダーを使用できます。

これを行う最も簡単な方法は、アペンダーを OSGi バンドルとしてパッケージ化し、org.ops4j.pax.logging.pax-logging-service バンドルのフラグメントとしてアタッチすることです。

たとえば、MyAppender を作成します。

public class MyAppender extends AppenderSkeleton {
...
}

次のようなマニフェストを含む OSGi バンドルとしてコンパイルしてパッケージ化します。

Manifest:
Bundle-SymbolicName: org.mydomain.myappender
Fragment-Host: org.ops4j.pax.logging.pax-logging-service
...

Apache Karaf system フォルダーでバンドルをコピーします。system フォルダーは、標準の Maven ディレクトリーレイアウト groupId/artifactId/version を使用します。

etc/startup.properties 設定ファイルで、pax-logging-service バンドルの前にバンドルをリストで定義します。

システムバンドルをリロードするには、クリーンな実行 (data フォルダーのパージ) で Apache Karaf を再起動する必要があります。これで、etc/org.ops4j.pax.logging.cfg 設定ファイルでアペンダーを直接使用できるようになります。

第20章 セキュリティー

Apache Karaf は、OSGi に準拠する方法で JAAS (Java Authentication and Authorization Service) を利用した高度で柔軟なセキュリティーシステムを提供します。

動的なセキュリティーシステムを提供します。

Apache Karaf セキュリティーフレームワークは、内部で使用され、以下へのアクセスを制御します。

  • OSGi サービス (開発者ガイドで説明)
  • コンソールコマンド
  • JMX レイヤー
  • WebConsole

また、アプリケーションはセキュリティーフレームワークを使用できます (詳細は開発者ガイドを参照してください)。

20.1. レルム

Apache Karaf は複数のレルムを管理できます。レルムには、このレルムの認証または承認に使用するログインモジュールの定義が含まれます。ログインモジュールはレルムの認証および承認を定義します。

jaas:realm-list コマンドは、現在定義されたレルムを一覧表示します。

karaf@root()> jaas:realm-list
Index | Realm Name | Login Module Class Name
-----------------------------------------------------------------------------------
1     | karaf      | org.apache.karaf.jaas.modules.properties.PropertiesLoginModule
2     | karaf      | org.apache.karaf.jaas.modules.publickey.PublickeyLoginModule

Apache Karaf は karaf という名前のデフォルトのレルムを提供していることがわかります。

このレルムには 2 つのログインモジュールがあります。

  • PropertiesLoginModule は、etc/users.properties ファイルをユーザー、グループ、ロール、およびパスワードのバックエンドとして使用します。このログインモジュールはユーザーを認証し、ユーザーのロールを返します。
  • PublickeyLoginModule は、特に SSHd によって使用されます。etc/keys.properties ファイルを使用します。このファイルには、ユーザーと各ユーザーに関連付けられた公開鍵が含まれます。

Apache Karaf は、追加のログインモジュールを提供します (詳細は開発者ガイドを参照してください) 。

  • JDBCLoginModule はデータベースをバックエンドとして使用します。
  • LDAPLoginModule は LDAP サーバーをバックエンドとして使用します。
  • SyncopeLoginModule は Apache Syncope をバックエンドとして使用します。
  • OsgiConfigLoginModule は設定をバックエンドとして使用します。
  • Krb5LoginModule は Kerberos サーバーをバックエンドとして使用します。
  • GSSAPILdapLoginModule は LDAP サーバーをバックエンドとして使用しますが、LDAP サーバーの認証を他のバックエンドに委譲します (通常は Krb5LoginModule)。

jaas:realm-manage コマンドを使用して、既存のレルムとログインモジュールを管理するか、独自のレルムを作成できます。

20.1.1. ユーザー、グループ、ロール、およびパスワード

これまで説明したように、Apache Karaf はデフォルトで PropertiesLoginModule を使用します。

このログインモジュールは、ユーザー、グループ、ロール、およびパスワードのストレージとして etc/users.properties ファイルを使用します。

最初の etc/users.properties ファイルには以下が含まれています。

################################################################################
#
#    Licensed to the Apache Software Foundation (ASF) under one or more
#    contributor license agreements.  See the NOTICE file distributed with
#    this work for additional information regarding copyright ownership.
#    The ASF licenses this file to You under the Apache License, Version 2.0
#    (the "License"); you may not use this file except in compliance with
#    the License.  You may obtain a copy of the License at
#
#       http://www.apache.org/licenses/LICENSE-2.0
#
#    Unless required by applicable law or agreed to in writing, software
#    distributed under the License is distributed on an "AS IS" BASIS,
#    WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
#    See the License for the specific language governing permissions and
#    limitations under the License.
#
################################################################################

#
# This file contains the users, groups, and roles.
# Each line has to be of the format:
#
# USER=PASSWORD,ROLE1,ROLE2,...
# USER=PASSWORD,_g_:GROUP,...
# _g_\:GROUP=ROLE1,ROLE2,...
#
# All users, grousp, and roles entered in this file are available after Karaf startup
# and modifiable via the JAAS command group. These users reside in a JAAS domain
# with the name "karaf".
#
karaf = karaf,_g_:admingroup
_g_\:admingroup = group,admin,manager,viewer

デフォルトではユーザーは karaf の 1 人のみであることが分かります。デフォルトのパスワードは karaf です。

karaf ユーザーは 1 つのグループ admingroup のメンバーです。

グループの先頭には常に g: が付けられます。このプレフィックスのないエントリーはユーザーです。

グループはロールのセットを定義します。デフォルトでは、admingroupgroupadminmanager、および viewer ロールを定義します。

つまり、karaf ユーザーは admingroup によって定義されたロールを持つことを意味します。

20.1.1.1. コマンド

jaas:* コマンドは、コンソールでレルム、ユーザー、グループ、および ロールを管理します。

20.1.1.1.1. jaas:realm-list

このセクションでは、これまでに jaas:realm-list を使用しました。

jaas:realm-list コマンドは、レルムと各レルムのログインモジュールを一覧表示します。

karaf@root()> jaas:realm-list
Index | Realm Name | Login Module Class Name
-----------------------------------------------------------------------------------
1     | karaf      | org.apache.karaf.jaas.modules.properties.PropertiesLoginModule
2     | karaf      | org.apache.karaf.jaas.modules.publickey.PublickeyLoginModule

ここでは、2 つのログインモジュール (PropertiesLoginModule および PublickeyLoginModule) が含まれる 1 つのレルム (karaf) があります。

index コマンドは、管理するレルム/ログインモジュールを簡単に識別するために jaas:realm-manage コマンドによって使用されます。

20.1.1.1.2. jaas:realm-manage

jaas:realm-manage コマンドは、レルム/ログインモジュールの編集モードを切り替え、ログインモジュールでユーザー、グループ、およびロールを管理できます。

管理するレルムおよびログインモジュールを識別するには、--index オプションを使用します。インデックスは jaas:realm-list コマンドによって表示されます。

karaf@root()> jaas:realm-manage --index 1

別の方法として、--realm および --module オプションを使用することもできます。--realm オプションはレルム名を想定し、--module オプションはログインモジュールクラス名を想定します。

karaf@root()> jaas:realm-manage --realm karaf --module org.apache.karaf.jaas.modules.properties.PropertiesLoginModule
20.1.1.1.3. jaas:user-list

編集モードの場合は、jaas:user-list を使用してログインモジュールのユーザーを一覧表示できます。

karaf@root()> jaas:user-list
User Name | Group      | Role
--------------------------------
karaf     | admingroup | admin
karaf     | admingroup | manager
karaf     | admingroup | viewer

ロール別のユーザー名とグループを確認できます。

20.1.1.1.4. jaas:user-add

jaas:user-add コマンドは、現在編集中のログインモジュールに新しいユーザ (およびパスワード) を追加します。

karaf@root()> jaas:user-add foo bar

変更 (ユーザーの追加) を「コミット」するには、jaas:update コマンドを実行します。

karaf@root()> jaas:update
karaf@root()> jaas:realm-manage --index 1
karaf@root()> jaas:user-list
User Name | Group      | Role
--------------------------------
karaf     | admingroup | admin
karaf     | admingroup | manager
karaf     | admingroup | viewer
foo       |            |

一方、ユーザーの追加をロールバックする場合は、jaas:cancel コマンドを使用できます。

20.1.1.1.5. jaas:user-delete

jaas:user-delete コマンドは、現在編集中のログインモジュールからユーザーを削除します。

karaf@root()> jaas:user-delete foo

jaas:user-add コマンドと同様に、jaas:update を使用して変更をコミット (またはロールバックの場合は jaas:cancel) する必要があります。

karaf@root()> jaas:update
karaf@root()> jaas:realm-manage --index 1
karaf@root()> jaas:user-list
User Name | Group      | Role
--------------------------------
karaf     | admingroup | admin
karaf     | admingroup | manager
karaf     | admingroup | viewer
20.1.1.1.6. jaas:group-add

jaas:group-add コマンドは、現在編集中のログインモジュールでグループをユーザーに割り当てます (最終的にグループを作成)。

karaf@root()> jaas:group-add karaf mygroup
20.1.1.1.7. jaas:group-delete

jaas:group-delete コマンドは、現在編集中のログインモジュールでグループからユーザーを削除します。

karaf@root()> jaas:group-delete karaf mygroup
20.1.1.1.8. jaas:group-role-add

jaas:group-role-add コマンドは、現在編集中のログインモジュールでグループのロールを追加します。

karaf@root()> jaas:group-role-add mygroup myrole
20.1.1.1.9. jaas:group-role-delete

jaas:group-role-delete コマンドは、現在編集中のログインモジュールでグループからロールを削除します。

karaf@root()> jaas:group-role-delete mygroup myrole
20.1.1.1.10. jaas:update

jaas:update コマンドは、ログインモジュールのバックエンドで変更をコミットします。たとえば、PropertiesLoginModule の場合、etc/users.propertiesjaas:update コマンドの実行後にのみ更新されます。

20.1.1.1.11. jaas:cancel

jaas:cancel コマンドは変更をロールバックし、ログインモジュールのバックエンドを更新しません。

20.1.2. パスワードの暗号化

デフォルトでは、パスワードは etc/users.properties ファイルにクリアテキストで保存されます。

etc/org.apache.karaf.jaas.cfg 設定ファイルで暗号化を有効にすることができます。

################################################################################
#
#    Licensed to the Apache Software Foundation (ASF) under one or more
#    contributor license agreements.  See the NOTICE file distributed with
#    this work for additional information regarding copyright ownership.
#    The ASF licenses this file to You under the Apache License, Version 2.0
#    (the "License"); you may not use this file except in compliance with
#    the License.  You may obtain a copy of the License at
#
#       http://www.apache.org/licenses/LICENSE-2.0
#
#    Unless required by applicable law or agreed to in writing, software
#    distributed under the License is distributed on an "AS IS" BASIS,
#    WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
#    See the License for the specific language governing permissions and
#    limitations under the License.
#
################################################################################

#
# Boolean enabling / disabling encrypted passwords
#
encryption.enabled = false

#
# Encryption Service name
#   the default one is 'basic'
#   a more powerful one named 'jasypt' is available
#       when installing the encryption feature
#
encryption.name =

#
# Encryption prefix
#
encryption.prefix = {CRYPT}

#
# Encryption suffix
#
encryption.suffix = {CRYPT}

#
# Set the encryption algorithm to use in Karaf JAAS login module
# Supported encryption algorithms follow:
#   MD2
#   MD5
#   SHA-1
#   SHA-256
#   SHA-384
#   SHA-512
#
encryption.algorithm = MD5

#
# Encoding of the encrypted password.
# Can be:
#   hexadecimal
#   base64
#
encryption.encoding = hexadecimal

encryption.enabled が true に設定されている場合、パスワードの暗号化が有効になります。

暗号化を有効にすると、ユーザーが最初にログインしたときにパスワードは暗号化されます。暗号化したパスワードの先頭と末尾に、\{CRYPT\} が付きます。パスワードを再暗号化するには、先頭と末尾の \{CRYPT\} がない状態でパスワードをリセットできます (etc/users.properties ファイルで)。Apache Karaf は、このパスワードが明確であることを検出し (先頭と末尾に \{CRYPT\} がないため)、再度暗号化します。

etc/org.apache.karaf.jaas.cfg 設定ファイルを使用すると、高度な暗号化動作を定義できます。

  • encryption.prefix プロパティーは、パスワードが暗号化されていることを「フラグ」するプレフィックスを定義します。デフォルトは \{CRYPT\} です。
  • encryption.suffix プロパティーは、パスワードが暗号化されていることを「フラグ」するサフィックスを定義します。デフォルトは \{CRYPT\} です。
  • encryption.algorithm プロパティーは、暗号化 (digest) に使用するアルゴリズムを定義します。使用できる値は MD2MD5SHA-1SHA-256SHA-384、および SHA-512 です。デフォルトは MD5 です。
  • encryption.encoding プロパティーは、暗号化されたパスワードのエンコーディングを定義します。使用できる値は hexadecimal または base64 です。デフォルト値は hexadecimal です。

20.1.3. 鍵による認証の管理

SSH レイヤーでは、Karaf はキーによる認証をサポートし、パスワードを提供せずにログインできます。

SSH クライアント (Karaf 自体によって提供される bin/client または OpenSSH などの ssh クライアント) は、Karaf SSHD (サーバー側) で SSH クライアントを識別するための公開鍵/秘密鍵のペアを使用します。

接続が許可された鍵は、次の形式に従って etc/keys.properties ファイルに格納されます。

user=key,role

デフォルトでは、Karaf は karaf ユーザーのキーを許可します。

# karaf=AAAAB3NzaC1kc3MAAACBAP1/U4EddRIpUt9KnC7s5Of2EbdSPO9EAMMeP4C2USZpRV1AIlH7WT2NWPq/xfW6MPbLm1Vs14E7gB00b/JmYLdrmVClpJ+f6AR7ECLCT7up1/63xhv4O1fnxqimFQ8E+4P208UewwI1VBNaFpEy9nXzrith1yrv8iIDGZ3RSAHHAAAAFQCXYFCPFSMLzLKSuYKi64QL8Fgc9QAAAIEA9+GghdabPd7LvKtcNrhXuXmUr7v6OuqC+VdMCz0HgmdRWVeOutRZT+ZxBxCBgLRJFnEj6EwoFhO3zwkyjMim4TwWeotUfI0o4KOuHiuzpnWRbqN/C/ohNWLx+2J6ASQ7zKTxvqhRkImog9/hWuWfBpKLZl6Ae1UlZAFMO/7PSSoAAACBAKKSU2PFl/qOLxIwmBZPPIcJshVe7bVUpFvyl3BbJDow8rXfskl8wO63OzP/qLmcJM0+JbcRU/53JjTuyk31drV2qxhIOsLDC9dGCWj47Y7TyhPdXh/0dthTRBy6bqGtRPxGa7gJov1xm/UuYYXPIUR/3x9MAZvZ5xvE0kYXO+rx,admin
注記

セキュリティー上の理由から、この鍵は無効になっています。クライアントごとにキーペアを作成し、etc/keys.properties ファイルを更新することが推奨されます。

キーペアを作成する最も簡単な方法は、OpenSSH を使用することです。

以下を使用してキーペアを作成できます。

ssh-keygen -t dsa -f karaf.id_dsa -N karaf

これで、公開鍵と秘密鍵が作成されます。

-rw-------  1 jbonofre jbonofre    771 Jul 25 22:05 karaf.id_dsa
-rw-r--r--  1 jbonofre jbonofre    607 Jul 25 22:05 karaf.id_dsa.pub

karaf.id_dsa.pub ファイルのコンテンツは、etc/keys.properties にコピーできます。

karaf=AAAAB3NzaC1kc3MAAACBAJLj9vnEhu3/Q9Cvym2jRDaNWkATgQiHZxmErCmiLRuD5Klfv+HT/+8WoYdnvj0YaXFP80phYhzZ7fbIO2LRFhYhPmGLa9nSeOsQlFuX5A9kY1120yB2kxSIZI0fU2hy1UCgmTxdTQPSYtdWBJyvO/vczoX/8I3FziEfss07Hj1NAAAAFQD1dKEzkt4e7rBPDokPOMZigBh4kwAAAIEAiLnpbGNbKm8SNLUEc/fJFswg4G4VjjngjbPZAjhkYe4+H2uYmynry6V+GOTS2kaFQGZRf9XhSpSwfdxKtx7vCCaoH9bZ6S5Pe0voWmeBhJXi/Sww8f2stpitW2Oq7V7lDdDG81+N/D7/rKDD5PjUyMsVqc1n9wCTmfqmi6XPEw8AAACAHAGwPn/Mv7P9Q9+JZRWtGq+i4pL1zs1OluiStCN9e/Ok96t3gRVKPheQ6IwLacNjC9KkSKrLtsVyepGA+V5j/N+Cmsl6csZilnLvMUTvL/cmHDEEhTIQnPNrDDv+tED2BFqkajQqYLgMWeGVqXsBU6IT66itZlYtrq4v6uDQG/o=,admin

また、クライアントに karaf.id_dsa 秘密鍵を使用するように指定します。

bin/client -k ~/karaf.id_dsa

または ssh

ssh -p 8101 -i ~/karaf.id_dsa karaf@localhost

20.1.4. RBAC

Apache Karaf はロールを使用してリソースへのアクセスを制御します。これは RBAC (ロールベースアクセス制御) システムです。

ロールは以下を制御するために使用されます。

  • OSGi サービスへのアクセス
  • コンソールへのアクセス (コマンドの実行の制御)
  • JMX へのアクセス (MBean や操作)
  • WebConsole へのアクセス

20.1.4.1. OSGi サービス

OSGi サービスの RBAC サポートの詳細は開発者ガイドで説明されています。

20.1.4.2. Console

コンソール の RBAC のサポートは、OSGi サービスの RBAC に特化しています。実際に、Apache Karaf では、すべてのコンソールコマンドは OSGi サービスとして定義されます。

コンソールのコマンド名は scope:name 形式に従います。

ACL (アクセスリスト) は etc/org.apache.karaf.command.acl.<scope>.cfg 設定ファイルで定義されます。<scope> はコマンドスコープです。

たとえば、etc/org.apache.karaf.command.acl.feature.cfg 設定ファイルを作成して、ACL を feature:* コマンドに定義できます。この etc/org.apache.karaf.command.acl.feature.cfg 設定ファイルでは、以下を設定できます。

list = viewer
info = viewer
install = admin
uninstall = admin

ここでは、viewer ロールが割り当てられているユーザーが feature:list および feature:info コマンドを実行できることを定義しますが、feature:install および feature:uninstall コマンドは、admin ロールを持つユーザーのみが実行できます。admin グループのユーザーには viewer ロールもあるため、すべてを実行できることに注意してください。

Apache Karaf コマンド ACL は以下を使用してアクセスを制御できます (指定のコマンドスコープ内) 。

  • コマンド名の正規表現 (例: name = role)
  • コマンド名とオプションまたは引数の値の正規表現 (例: 100 を超える引数の値でのみ名前を実行する name[/.[0-9][0-9][0-9]+./] = role)

コマンド名とオプション/引数はいずれも、完全一致または正規表現の一致をサポートします。

デフォルトでは、Apache Karaf は以下のコマンド ACL を定義します。

  • etc/org.apache.karaf.command.acl.bundle.cfg 設定ファイルは、bundle:* コマンドの ACL を定義します。この ACL は、システムバンドルの bundle:* コマンドの実行を admin ロールが割り当てられたユーザーのみに制限しますが、システム以外のバンドルの bundle:* コマンドは、manager ロールを持つユーザーが実行できます。
  • etc/org.apache.karaf.command.acl.config.cfg 設定ファイルは、config:* コマンドの ACL を定義します。この ACL は、jmx.acl.*org.apache.karaf.command.acl.*、および org.apache.karaf.service.acl.* 設定 PID を持つ config:* コマンドの実行を、admin ロールを持つユーザーに制限します。他の設定 PID の場合、manager ロールを持つユーザーは config:* コマンドを実行できます。
  • etc/org.apache.karaf.command.acl.feature.cfg 設定ファイルは、feature:* コマンドの ACL を定義します。admin ロールを持つユーザーのみが、feature:install および feature:uninstall コマンドを実行できます。その他の feature:* コマンドは、任意のユーザーが実行できます。
  • etc/org.apache.karaf.command.acl.jaas.cfg 設定ファイルは、jaas:* コマンドの ACL を定義します。admin ロールを持つユーザーのみが jaas:update コマンドを実行できます。その他の jaas:* コマンドは、任意のユーザーが実行できます。
  • etc/org.apache.karaf.command.acl.kar.cfg 設定ファイルは、kar:* コマンドの ACL を定義します。admin ロールを持つユーザーのみが、kar:install および kar:uninstall コマンドを実行できます。その他の kar:* コマンドは、任意のユーザーが実行できます。
  • etc/org.apache.karaf.command.acl.shell.cfg 設定ファイルは、shell:* および「direct」コマンドの ACL を定義します。admin ロールを持つユーザーのみが、shell:editshell:execshell:new、および shell:java コマンドを実行できます。その他の shell:* コマンドは、任意のユーザーが実行できます。

これらのデフォルト ACL を変更し、追加のコマンドスコープに独自の ACL を追加します(例: Apache Karaf Cellar の場合は etc/org.apache.karaf.command.acl.cluster.cfg、Apache Camel, …​ etc/org.apache.karaf.command.acl.camel.cfg

etc/system.propertieskaraf.secured.services プロパティーを編集して、コマンドの RBAC サポートを微調整できます。

#
# By default, only Karaf shell commands are secured, but additional services can be
# secured by expanding this filter
#
karaf.secured.services = (&(osgi.command.scope=*)(osgi.command.function=*))

20.1.4.3. JMX

コンソールコマンドと同様に、JMX レイヤーに ACL (AccessLists) を定義できます。

JMX ACL は etc/jmx.acl<ObjectName>.cfg 設定ファイルで定義されます。<ObjectName> は MBean オブジェクト名です (たとえば org.apache.karaf.bundleorg.apache.karaf;type=Bundle MBean を表します)。

etc/jmx.acl.cfg は最も汎用的な設定ファイルであり、特定の設定ファイルが見つからない場合に使用されます。これには「グローバル」ACL 定義が含まれます。

JMX ACL は、(JMX MBean 内で) 以下を使用してアクセスを制御できます。

  • 操作名の正規表現 (例: operation* = role)
  • 操作引数値の正規表現 (例: operation(java.lang.String, int)[/([1-4])?[0-9]/,/.*/] = role)

デフォルトでは、Apache Karaf は以下の JMX ACL を定義します。

  • etc/jmx.acl.org.apache.karaf.bundle.cfg 設定ファイルは org.apache.karaf:type=bundle MBean の ACL を定義します。この ACL は、admin ロールを持つユーザーのみにシステムバンドルの setStartLevel()start()stop()、および update() 操作を制限します。他の操作は、manager ロールを持つユーザーが実行できます。
  • etc/jmx.acl.org.apache.karaf.config.cfg 設定ファイルは org.apache.karaf:type=config MBean の ACL を定義します。この ACL は、admin ロールを持つユーザーのみに jmx.acl*org.apache.karaf.command.acl*、および org.apache.karaf.service.acl* 設定 PID への変更を制限します。他の操作は、manager ロールを持つユーザーが実行できます。
  • etc/jmx.acl.org.apache.karaf.security.jmx.cfg 設定ファイルは org.apache.karaf:type=security,area=jmx MBean の ACL を定義します。この ACL は、viewer ロールを持つユーザーに canInvoke() 操作の呼び出しを制限します。
  • etc/jmx.acl.osgi.compendium.cm.cfg 設定ファイルは osgi.compendium:type=cm MBean の ACL を定義します。この ACL は、admin ロールを持つユーザーのみに jmx.acl*org.apache.karaf.command.acl*、および org.apache.karaf.service.acl* 設定 PID への変更を制限します。他の操作は、manager ロールを持つユーザーが実行できます。
  • etc/jmx.acl.java.lang.Memory.cfg 設定ファイルは、コア JVM Memory MBean の ACL を定義します。この ACL は、 gc 操作の呼び出しを manager ロールを持つユーザーのみに制限します。
  • etc/jmx.acl.cfg 設定ファイルは最も汎用的なファイルです。ここで定義された ACL は、他の特定の ACL が一致しない場合に使用されます (特定の ACL によって)。これは別の MBean 固有の etc/jmx.acl.*.cfg 設定ファイルで定義される ACL です。list*()get*()is*() 操作は、viewer ロールを持つユーザーが実行できます。set*() およびその他の *() 操作はすべて、admin ロールを持つユーザーが実行できます。

20.1.4.4. WebConsole

Apache Karaf WebConsole はデフォルトで利用できません。これを有効にするには、webconsole 機能をインストールする必要があります。

karaf@root()> feature:install webconsole

WebConsole では、コンソールや JMX などの粒度の細かい RBAC をサポートしていません。

admin ロールを持つすべてのユーザーが WebConsole にログインし、任意の操作を実行できます。

20.1.5. SecurityMBean

Apache Karaf は、現在のユーザーが指定の MBean や操作を呼び出せるかどうかを確認するために JMX MBean を提供します。

canInvoke() 操作は現在のユーザーのロールを取得し、最終的に指定された引数値を使用して、ロールが MBean や操作を呼び出しできるかどうかを確認します。

20.1.5.1. 操作

  • canInvoke(objectName) は、現在のユーザーが objectName で MBean を呼び出す場合は true を返します。それ以外の場合は false を返します。
  • canInvoke(objectName, methodName) は、現在のユーザーが methodName 操作を objectName のある MBean で呼び出す場合は true を返します。それ以外の場合は falseを返します。
  • canInvoke(objectName, methodName, argumentTypes) は、現在のユーザーが引数型 argumentTypes の配列を持つ操作 methodNameobjectName のある MBean で呼び出しできる場合は true を返します。それ以外の場合は false を返します。
  • canInvoke(bulkQuery)canInvoketrue または false の場合、bulkQuery 表形式データの各操作が含まれる表形式データを返します。

20.1.6. セキュリティープロバイダー

一部のアプリケーションでは、特定のセキュリティープロバイダー (BouncyCastle など) が利用可能でなければなりません。

JVM は、このような jar の使用に制限を課します。それらは署名され、ブートクラスパスで利用可能でなければなりません。

これらのプロバイダーをデプロイする方法の 1 つは、$JAVA_HOME/jre/lib/ext の JRE フォルダーに配置し、そのプロバイダーを登録するためにセキュリティーポリシー設定 ($JAVA_HOME/jre/lib/security/java.security) を変更することです。

このアプローチは正常に動作しますが、グローバルな効果があり、それに応じてすべてのサーバーを設定する必要があります。

Apache Karaf は、追加のセキュリティープロバイダーを設定する簡単な方法を提供します。* プロバイダー jar を lib/ext に配置 * etc/config.properties 設定ファイルを変更して以下のプロパティーを追加

org.apache.karaf.security.providers = xxx,yyy

このプロパティーの値は、登録するプロバイダークラス名のコンマ区切りリストです。

たとえば、bouncycastle セキュリティープロバイダーを追加するには、以下を定義します。

org.apache.karaf.security.providers = org.bouncycastle.jce.provider.BouncyCastleProvider

さらに、すべてのバンドルがそれらにアクセスできるように、これらのプロバイダーからクラスへのアクセスを提供することもできます。

これには、同じ設定ファイルの org.osgi.framework.bootdelegation プロパティーを変更します。

org.osgi.framework.bootdelegation = ...,org.bouncycastle*