Menu Close

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. サーバーモードで実行されているインスタンスの停止

以下のように InstallDir/bin ディレクトリーから stop(.bat) を呼び出すことで、ローカルに実行中の 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

Username および Password は、新しいユーザー認証情報です。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 アクセス制御のための標準ロール

ロール説明

ビューアー

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

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 をインストールすることは、win sw でサポートされています

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 などの パス(デフォルトは ${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 Portal でデーモン コマンドおよび 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 コンテナーにデプロイできるルートを構築するプロジェクトを作成します。

以下の例は、GroupId:ArtifactId: Version と Maven archetype コマンドと Maven archetype コマンドを使用して 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 を設定します。以下の例のように、package 要素の内容を 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 ファイルとプロジェクトのブループリントファイル(META -INF/springにあります)を変更する必要があります。

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

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

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-first アプローチ- cxf-java2ws-plugin プラグインを使用します。
  • wsdl-first アプローチ- 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「バンドルのシンボリック名の設定」 に示されるように、プラグインの 命令 要素に 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「バンドル名の設定」 に示されるように Bundle-Name 子をプラグインの instructions 要素に追加します。

例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 要素に追加します。

例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 下)のすべてのパッケージ(src /main/java下) および すべてのパッケージ( impl または. internal を含むパッケージ )によって入力されます。

重要

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

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

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

除外するパッケージを指定して、エントリーの前に ! を付けることができます。たとえば、エントリー !com.fuse.demo.private は、パッケージ com.fuse.demo.private を除外します。

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

たとえば、com.fuse.demo パッケージを除き、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 プロパティーを、バンドルのコンテンツによって参照されるすべてのパッケージのリストで設定します。

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

バンドルによってインポートされるパッケージの一覧を指定するには、プラグインの instructions 要素に Import-Package 子を追加します。パッケージ一覧の構文は、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 shell コマンドによって、"managed service" と "managed service factory" を区別します。したがって、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 console コマンドを使用してバンドルをアンデプロイすることもできます。

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 プラットフォームでは、このコマンドの ファイル 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 コマンドを使用すると、Karaf に対してローカルの Maven リポジトリーを監視し、ローカルの Maven リポジトリーで変更されると、特定のバンドルを自動的に再インストールできます。

たとえば、特定の bundle-with バンドル 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): 開始状態は、解決済み状態とアクティブ状態の間の一時的な状態です。バンドルの起動時に、コンテナーはバンドルのリソースを作成する必要があります。コンテナーは、バンドルの bundle activator の start() メソッドも呼び出します。
  4. アクティブ (Active): アクティブ状態の作業に使用できます。バンドルがアクティブ状態で行う作業は、バンドルの内容によって異なります。たとえば、JAX-WS サービスプロバイダーが含まれるバンドルは、サービスがリクエストを許可できることを示します。
  5. 停止 (Stopping): 停止状態は、アクティブ状態と解決済み状態の間の一時的な状態です。バンドルが停止すると、コンテナーはバンドルのリソースをクリーンアップする必要があります。コンテナーは、バンドルの bundle activator の 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 でバンドルを 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 ヘッダーには一覧表示されません。
  • OSGI-INF/blueprint ディレクトリーなど)Blueprint XML ファイルを定義すると、Blueprint XML ファイルからの依存関係 は自動的にランタイム時に解決されます

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

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

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

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

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

    この設定により、OSGi はコンテナーにすでにインストールされている バンドル を使用して依存関係を解決でき、通常の依存関係解決メカニズム( 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. 概要

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

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

カスタム features リポジトリーを定義していない場合は、以下のように作成できます。ファイルシステム上の feature リポジトリーの便利な場所を選択します(例: C:\Projects\features.xml-andrae favorite テキストエディター)、以下の行をこれに追加します。

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

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

注記

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

9.3. カスタム 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 で、バンドルの場所を指定できます( 15章URL ハンドラーを参照)。オプションで feature 要素で 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 コマンドは、カーネルがすべての feature リポジトリーを再読み取りするように強制します。このコマンドを実行しなかった場合には、カーネルは、リポジトリーに対して行った最近の変更を認識しません(特に新機能はリストに表示されません)。

機能の長い一覧をスクロールしないようにするには、以下のように 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 の機能サービスへの追加

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

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

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

features:listUrl console コマンドを入力し、以下のように、登録されたすべての feature repository 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 要素の子として 追加することで、これらの依存関係を指定できます。各子要素には、現在の機能が依存する機能の名前 が含まれます。依存関係機能で機能をデプロイすると、依存機能がコンテナーにインストールされているかどうかが確認されます。そうでない場合は、依存関係メカニズムにより、不足している依存関係 (および再帰的な依存関係) が自動的にインストールされます。

たとえば、カスタム 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>

このブループリント XML ファイルが example-camel-bundle バンドルにデプロイされると、プロパティー参照 ${prefix} は feature リポジトリーの 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. コンソールでのインストール

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

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

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

注記

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

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

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

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

アンインストールすると、function :list を呼び出すと、この機能は引き続き表示されますが、そのステータスには [uninstalled] というフラグが付けられるようになりました。

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

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

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 コンテナーの実行中にInstallDir/deploy ディレクトリーから features ファイルを削除するだけです。

重要

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

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- 起動時に読み込む feature リポジトリーのコンマ区切りリスト。
  • 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 の変換

概要

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

構文

wrap: プロトコルには、以下の基本的な構文があります。

wrap:LocationURL

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

注記

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

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

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

Wrap および install

以下の例は、1 つの console コマンドを使用してリモート 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 reference 」を参照してください。

第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 ファイルの場所

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

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

必須の依存関係

OSGi サービスの依存関係は、デフォルトで必須です(参照要素で availability 属性を optional または reference -list 要素で 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 ヘッダーの値はセミコロン区切りリストです。1 つ目の項目は実際のバンドルシンボリック名、2 つ目の項目、Blueprint.graceperiod:=true )で、猶予期間および 3 つ目のアイテム、Blueprint.timeout:= 10000 を 10 秒のタイムアウトを指定します。

12.1.2. サービス Bean の定義

概要

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

Blueprint Bean 要素

Blueprint Bean 要素は、Blueprint スキーマ名前空間 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 名前空間を宣言し、Blueprint の xml に プロパティープレースホルダー Bean を追加する必要があります。Property-Placeholder Bean を使用して、プロパティーファイルの場所をブループリントに宣言します。

<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>

プロパティープレースホルダーの 設定オプションは 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 を参照する サービス 要素を定義し、interface 子要素を使用して公開された インターフェース を指定します。

たとえば、以下の Blueprint 設定コードを使用して、公開 Java インターフェース(org.fusesource.example .Account および org.fusesource.example.SavingsAccount)のリスト の下に Savings Account クラスのインスタンスをエクスポートすることができます。

<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 要素は、同じサービス 要素で同時に使用することはできません。どちらか一方を使用する必要があります。

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 値は、Savings AccountImpl によって実装されたパブリックインターフェースをすべて登録する必要があることを示していますauto-export 属性には、以下の有効な値を使用できます。

disabled
自動エクスポートを無効にします。これがデフォルトになります。
interfaces
実装されたすべてのパブリック Java インターフェースでサービスを登録します。
class-hierarchy
オブジェクトクラス を除き、独自のタイプ(クラス)およびすべてのスーパーユーザー(super-classes)の下にサービスを登録します。
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」を参照してください。

注記

エントリー 要素は、Blueprint 名前空間に属します。Blueprint の実装で beans:entry 要素の使用は標準ではありません。

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

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

  • osgi.service.blueprint.compname-is は、Bean がインラインでない限り、サービスの bean 要素の ID に常に設定されます(つまり、Bean はサービス要素の子要素として定義されます )。インライン化された Bean は常に匿名です。
  • service.ranking -is は、ランク属性がゼロ以外の場合には自動的に設定されます。

ranking 属性の指定

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

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

登録リスナーの指定

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

たとえば、以下の Blueprint 設定は、Enrollment -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 属性は登録 コールバックを受け取る listener メソッドの名前を指定し、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) {
        ...
    }
}

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

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

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

概要

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

サービス参照の管理

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

参照マネージャー

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

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

deploy simple svc 01

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

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

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

参照リストマネージャー

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

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

deploy simple svc 02

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

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

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

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

たとえば、ステートレスの SavingsAccount サービスを参照するには( 例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>

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

クライアントクラスにインジェクトされた bean プロパティーは、Savings Account から割り当て可能なタイプにすることができます。たとえば、以下のように 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 サービスを参照するには( 例12.1「単一のインターフェースを使用したサンプルサービスのエクスポート」を参照)、以下のように reference-list 要素を定義します。

<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)の両方に一致するには、以下のように reference 要素の interface 属性と component-name 属性の両方を指定します。

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

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

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

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

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

(bank.name=HighStreetBank)

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

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

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

フィルターは、インターフェースと コンポーネント名の設定と組み合わせることもできます。この場合は、 指定した条件をすべて一致させる必要があります。

たとえば、Savings Account タイプの ステートレス サービスに一致し、HighStreetBank と同等の bank .name サービスプロパティーを使用する場合は、以下のように 参照 要素を定義します。

<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 属性を設定して、参照 要素または参照 リスト 要素の依存関係の動作をカスタマイズできます。

availability 属性の値は 2 つあります。

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

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

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

参照リスナーの指定

OSGi 環境の動的な性質に対応するため、オプションの availability-it に宣言したサービス参照の一部が、バッキングサービスがレジストリーにバインドされている場合、またレジストリーからバインドされないタイミングを追跡する場合に便利です。サービスバインディングおよびバインド解除イベントの通知を受け取るには、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>

上記の設定では、バインドおよびバインド解除 イベントをリッスンするコールバックとして 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);
    }

}

メソッド名 のBind および onUnbind は、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 archetype は、汎用 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 バンドルプラグインの設定で、以下のように bundle 命令を変更して 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 サービスとしてエクスポートします

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. プロジェクトの-open a command prompt をビルドして、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 ハンドラー によって認識される 構文の詳細について、ファイル 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 サービスを見つけ、その上で say Hello() メソッドを呼び出します。

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 archetype は、汎用 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>

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

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 クラスは、hello WorldSvc bean プロパティーの getter および setter メソッドを定義し、インジェクションによって Hello World サービスへの参照を受信できるようにします。init() メソッドは、Bean 初期化フェーズ中にプロパティーインジェクションの後に呼び出されます。つまり、通常、このメソッドの範囲内で Hello World サービスを呼び出すことができます。

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

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

  1. -open a command prompt プロジェクトをビルドして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 ハンドラー によって認識される 構文の詳細について、ファイル 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 インターフェースは HelloBoston Impl クラスによって実装されることが前提になります(表示されません)。

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 要素を使用して OSGi 言語で 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. /camel/camel -jms/src/main ディレクトリーから Fuse インストールの FUSE_HOME/etc ディレクトリーに org.ops4j.connectionfactory- amq7.cfg ファイルをコピーします。正しいブローカー URLと クレデンシャルの内容を確認します。デフォルトでは、ブローカー URL は AMQ 7 の CORE プロトコルに従って tcp://localhost:61616 に設定されます。クレデンシャルは admin/admin に設定されます。外部ブローカーに合わせてこれらの詳細を変更します。
  4. Windows で ./bin/fuse on Linux または 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 ファイルにコピーされたファイルはオーダーファイルです。数分待ってから、/camel/camel-jms/work/jms/output ディレクトリーを確認します。ファイルは、宛先の国に応じて、個別のディレクトリーに分類されます。

    • /camel/camel-jms/work/jms/output/others/ order1.xml、order2.xml および order4. xml
    • order3.xml and order5.xml in /camel/camel-jms/work/jms/output/us
    • order6.xml in /camel/camel-jms/work/jms/output/fr
  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 ディレクトリーに移動し、Windows では ./bin/fuse (Linux の場合は 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-spec はロックを実装する Java クラスに対応します。単純なファイルロックの場合は、常に org.apache.karaf.main.SimpleFileLock である必要があります。
  • karaf.lock.dir- ロックファイルが書き込まれるディレクトリーを指定します。マスターとスレーブのインストール両方で同じである必要があります
  • karaf.lock.delay-specify(ミリ秒単位)、ロックの再取得を試行するまでの遅延。

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

概要

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

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

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

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

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

    たとえば、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 start スクリプト(または子インスタンスの 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 コーディネートのみが必要になります。以下の例は、groupId、org.fusesource.example artifactIdbundle-demo を使用して Maven バンドル を参照します。

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

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

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 バージョン範囲の構文を使用) を指定できます。角括弧([ and ]-to は包含範囲および括弧 および ))を表すものを使用して、排他的範囲を指定します。たとえば、範囲 [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 設定には、ハンドラーによって現在使用されているローカルリポジトリーの場所が表示され、リポジトリー 設定はハンドラーで現在使用されているリモートリポジトリー一覧を表示します。

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 プロパティーファイルを参照します。任意の 命令は、バンドル変換の実行方法を指定する 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

設定された [a-zA-Z0-9_-] 以外の文字がアンダースコア(_)に置き換えられます

15.4.4. 例

以下の Wrap URL は、Maven リポジトリーの commons-logging JAR のバージョン 1.1 を見つけ、デフォルトの 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. 参照資料

ラップされた 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. デフォルトの命令

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

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

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

Import-Package

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

Export-Package

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

Bundle-SymbolicName

設定した [a-zA-Z0-9_-\.] の文字がピリオドで置き換えられている WAR ファイルの名前

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 ディレクトリー内の a .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

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

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 の形式を取ります。512 M は 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 を使用するかどうかを決定します。

以下の ワーカー パラメーターを指定できます。

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>

以下の スレッドParameters を指定できます。

minThreads
ワーカータスクスレッドプールの「コア」スレッドの数を指定します。通常、これは適度に高く、CPU コアあたり少なくとも 10 である必要があります。
maxThreads
ワーカータスクスレッドプールの最大スレッド数を指定します。

以下の ワーカー パラメーターを指定できます。

workerIOThreads
ワーカーに作成する I/O スレッドの数を指定します。指定されていない場合、デフォルトが選択されます。デフォルト値が CPU コアごとに 1 つの IO スレッドであれば妥当です。
workerIOName
ワーカーの名前を指定します。指定しないと、デフォルトの「XNIO-1」が選択されます。

16.5. 設定ファイルの命名規則

設定ファイルの命名規則は、設定が OSGi Managed Service または OSGi Managed Service ファクトリーであるかどうかによって異なります。

OSGi Managed Service の設定ファイルは、以下の命名規則に従います。

<PID>.cfg

ここで、<PID> は OSGi 管理サービス の永続 ID です(OSGi Configuration Admin 仕様で定義されます)。通常、永続 ID はドットで区切られた(例: org.ops4j.pax.web )です。

OSGi Managed Service Factory の設定ファイルは、以下の命名規則に従います。

<PID>-<InstanceID>.cfg

ここで、& lt;PID> は OSGi Managed Service Factory の永続 ID です。マネージドサービスファクトリーの <PID> の場合には、 ハイフンとそれに続く任意のインスタンス ID <InstanceID> を追加できます。マネージドサービスファクトリーは、見つかった各 <InstanceID> に一意のサービスインスタンスを作成します。

16.6. Java オプションの設定

Java オプションは、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 には scope として 機能があり、名前として リストします。

Karaf はコマンドをスコープによって「グループ化」します。各スコープはサブシェルを形成します。

完全修飾名 (scope:name) でコマンドを直接実行できます。

karaf@root()> feature:list
...

または、サブシェルに入り、コンテキストなコマンドを入力します。

karaf@root()> feature
karaf@root(feature)> list

サブシェル名(ここでは 機能)を入力してサブシェルに直接入力できます。サブシェルから別のサブシェルに直接「切り替える」ことができます。

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 コマンドを使用して、完了モードを「fly」に変更することもできます(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 コマンドは新しいエイリアスを作成します。たとえば、list -installed-features エイリアスを実際の feature:list -i コマンドに指定するには、以下を実行できます。

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 をシャットダウンする短い形です(alias to system:shutdown -h -f command)。
  • help は、ヘルプを表示する短い形です(* :help コマンドのエイリアス)。
  • man は 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 s the current console display
  • shell:completion: completion mode(現在の完了モードを表示または変更)
  • shell:date は現在の日付を表示します(オプションでフォーマットを使用)。
  • shell:each は、
  • shell:echo echoes(stdout)に引数を出力
  • shell:edit は、現在のファイルまたは URL でテキストエディターを呼び出します。
  • shell:env は、シェルセッション変数の値を表示または設定します。
  • shell:exec run a system command
  • shell:grep は、指定のパターンに一致する行を出力します。
  • shell:head は入力の最初の行を表示します。
  • shell:history がコマンド履歴を出力します。
  • shell:if を使用すると、スクリプトで条件(if、その他のブロック)を使用できます。
  • shell:info は、現在の Karaf インスタンスに関するさまざまな情報を出力します。
  • shell:java が Java アプリケーションを実行します。
  • shell:less file pager
  • shell:logout s shell from current session
  • shell:more is a file pager
  • shell:new creates a new Java object
  • shell:printf formats and prints arguments
  • shell:sleep sleeps then wakes up
  • shell:sort write sorted concatenation of all files to stdout
  • shell:source は、スクリプトに含まれるコマンドを実行します。
  • shell:stack-traces-print は、コマンドの実行によって例外がスローされるとコンソールのフルスタックトレースを出力します。
  • shell:tac は STDIN をキャプチャーし、文字列として返します。
  • shell:tail は入力の最後の行を表示します。
  • shell:threads が現在のスレッドを出力する
  • shell:watch はコマンドを定期的に実行し、出力を更新します。
  • shell:wc は、各ファイルの改行、単語、およびバイト数を出力します。
  • 条件が true である間、shell:while loop

コマンドの完全修飾名を使用する必要はありません。一意である限り、コマンド名を直接使用できます。したがって、'shell:head' の代わりに 'head' を使用できます。

ここでも、help コマンドまたは --help オプションを使用して、これらのコマンドの詳細とオプションをすべて見つけることができます。

16.9.3.7. スクリプト

Apache Karaf コンソールは、Unix 上の bash または csh と同様に完全なスクリプト言語をサポートします。

(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 でアクセス可能な名前 リストで 「session」変数を作成していることに注意してください。

$it 変数は、現在のオブジェクトに対応する暗黙的な変数です(ここでは、リストの現在の反復値)。

[] でリストを作成すると、Apache Karaf コンソール は Java Array を作成します。つまり、ArrayList オブジェクトで利用可能なメソッドを使用できます (たとえばインスタンスの get や size など) 。

karaf@root()> list = ["Hello" world]; echo ($list get 0) ($list get 1)
Hello world

ここでは、オブジェクトのメソッドの呼び出しは直接 (オブジェクトメソッド引数) を使用することに注意してください。ここで ($list get 0)$list.get(0) を意味し 、$list は 2.16.840.1. になります。

クラス 表記は、オブジェクトの詳細を表示します。

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 リポジトリー」です。機能のインストールを可能にする前に、機能を提供する機能リポジトリーを登録する必要があります(後述 : feature:repo-add コマンドまたは FeatureMBean を使用)。

たとえば、以下の XML ファイル(または「機能リポジトリー」)は、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 が含まれます(詳細は [Artifacts リポジトリーおよび URL セクション|urls] を参照)。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 を使用して登録されます。

features 状態は、Apache Karaf キャッシュ( KARAF_DATA フォルダー)に保存されます。Apache Karaf は再起動でき、以前にインストールした機能は、再起動後も引き続きインストールされた状態を保ち、利用できます。クリーンな再起動を行ったり、Apache Karaf キャッシュを削除すると( KARAF_DATA フォルダーを削除)、以前登録した機能がすべて失われ、インストールされた機能がすべて失われます。機能を登録し、再び機能をインストールする必要があります。この動作を防ぐには、機能をブート機能として指定します。

16.10.5. ブート機能

一部の機能を、ブート機能として記述できます。起動機能は、以前 feature :install または feature MBean を使用してインストールされていない場合でも、Apache Karaf によって自動的にインストールされます。

Apache Karaf 機能設定は etc/org.apache.karaf.features.cfg 設定ファイルにあります。

この設定ファイルには、ブート機能の定義に使用する 2 つのプロパティーが含まれます。

  • featuresRepositories には、機能リポジトリー(機能 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 設定ファイルで定義された値と比べて開始レベルが等しくなり ます。

この値は、機能 XML の <bundle/> 要素の start-level 属性によって "overrided" にすることができます。

  <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 機能がインストールされると、他の機能 も自動的にインストールされます。

依存する機能にバージョン範囲を定義できます。

<feature name="spring-dm">
  <feature version="[2.5.6,4)">spring</feature>
  ...
</feature>

範囲で利用可能な最新バージョンを持つ機能がインストールされます。

1 つのバージョンを指定すると、範囲の上限はないとみなされます。

何も指定されていない場合、利用可能な最新バージョンがインストールされます。

バージョンを正確に指定するには 、[3.1,3.1] などのクローズされた範囲を使用します。

16.10.9.1. 機能の前提条件

前提条件機能は、特別な種類の依存関係です。依存性のある機能タグに 前提条件 属性を追加する場合は、実際の機能をインストールする前にインストールを強制し、依存する機能でバンドルをアクティブ化します。これは、指定の機能に登録されたバンドルが、ラップwar などの事前インストールされた URL を使用していない場合に役に立ちます

16.10.10. 機能設定

機能 XML の <config/> 要素を使用すると、機能的に(設定 PID で識別)設定の作成や追加が可能になります。

<config name="com.foo.bar">
  myProperty = myValue
</config>

<config/> 要素の name 属性は、設定 PID に対応します(詳細は [Configuration section|configuration] を参照してください)。

この機能のインストールは、etc フォルダーの com.foo.bar.cfg という名前のファイルをドロップする場合と同じ効果があります。

<config/> 要素のコンテンツは、key=value 標準に続くプロパティーセットです。

16.10.11. 機能設定ファイル

<config/> 要素を使用する代わりに、& lt;configfile/> 要素を指定できます。

<configfile finalname="/etc/myfile.cfg" override="false">URL</configfile>

<config/> 要素を使用する場合)Apache Karaf 設定レイヤーを直接操作する代わりに、& lt;configfile/> 要素は URL で指定されたファイルを直接取得し、finalname 属性で指定された場所のファイルをコピーします。

指定されていない場合、場所は KARAF_BASE 変数から相対します。${karaf.home}、${karaf.base}、${karaf.etc}、またはシステムプロパティーなどの変数を使用することもできます。

たとえば、以下のようになります。

<configfile finalname="${karaf.etc}/myfile.cfg" override="false">URL</configfile>

ファイルが目的の場所にすでに存在する場合は、既存のファイルにカスタマイズが含まれている可能性があるため、そのファイルは保持され、設定ファイルのデプロイメントはスキップされます。この動作は、上書きを 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 コマンドは、登録済み機能リポジトリーをすべて表示します。

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 は、機能リポジトリー 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

feature リポジトリー(および Apache Karaf で利用可能な新機能など)を登録するには、features:repo-add コマンドを使用する必要があります。

feature:repo-add コマンドには name/url 引数が必要です。この引数は、以下を受け入れます。

  • features リポジトリーの URL。features XML ファイルへの直接 URL になります。ユーザーガイドの「アーティファクトリポジトリーおよび URL」セクションで説明されている URL はサポートされます。
  • etc/org.apache.karaf.features.repos.cfg 設定ファイルで定義された機能リポジトリー名。

etc/org.apache.karaf.features.repos.cfg は、「pre-installed/available」機能リポジトリーの一覧を定義します。

################################################################################
#
#    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

任意の バージョンの 引数を指定しないと、Apache Karaf は利用可能な機能リポジトリーの最新バージョンをインストールします。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 設定ファイルに定義されている feature リポジトリー名を提供する代わりに、feature:repo-add コマンドに features リポジトリーの URL を直接指定できます。

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 リポジトリーを登録し、この機能 リポジトリーに記載されているすべての機能をインストールします。

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 コマンドは、登録した機能リポジトリーから削除します。

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 コマンドは、登録されたものから feature リポジトリーを削除します。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 コマンドは、利用可能なすべての機能を一覧表示します(登録済み機能リポジトリーによって提供されます)。

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

デフォルトでは、機能をインストールすると自動的にインストールされます。ただし、feature:install コマンドに -s オプションを指定できます。

機能をインストールすると (起動したかどうかに関わらず)、機能で定義されているバンドルによって提供されるすべてのパッケージが使用可能になり、他のバンドルのワイヤリングに使用できます。

機能を起動すると、すべてのバンドルが起動されるため、機能よってサービスも公開されます。

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. Deployer

ファイルを 直接デプロイ フォルダーに置いて、機能 XML を「ホットデプロイ」することができます。

Apache Karaf は機能デプロイヤーを提供します。

deploy フォルダーで機能 XML を削除すると、機能デプロイヤー:機能 XML を機能リポジトリーとして登録する*、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 つの属性を提供します。

  • 機能は、利用可能なすべての機能の表的なデータセットです。
  • リポジトリーは、登録されているすべての機能リポジトリーの表的なデータセットです。

リポジトリー 属性は以下の情報を提供します。

  • Name は features リポジトリーの名前です。
  • URI は、このリポジトリーの機能 XML への URI です
  • 機能は、この機能リポジトリーが提供する全機能(名前およびバージョン)の表的なデータセットです。
  • リポジトリーは、この機能リポジトリーにおいて、機能リポジトリーの表的なデータセットです。

Features 属性は以下の情報を提供します。

  • name は機能 の名前です
  • version は、機能のバージョンです。
  • installed はブール値です。true の場合、この機能が現在インストールされていることを意味します。
  • バンドルは 機能に記述されるすべてのバンドル(バンドル URL)の表的なデータセットです。
  • 設定は 機能に説明されている全設定の表的なデータセットです。
  • 設定ファイルは 機能に記述されるすべての設定ファイルの表的なデータセットです。
  • 依存関係は、機能に記述されるすべての依存機能の表的なデータセットです。

16.10.14.2. 操作

  • addRepository(url) は features リポジトリーを url に追加します。url は、feature:repo-add コマンドの場合と同様に 名前 を指定できます。
  • addRepository(url, install)url で features リポジトリーを追加し、install が true の場合はすべてのバンドルを自動的にインストールします。url は、feature:repo-add コマンドのように 名前 を指定できます。
  • removeRepository(url) は、URL が含まれる features リポジトリーを削除します url は、feature:repo-remove コマンドのように 名前 を指定できます。
  • installFeature(name)名前で 機能をインストールします。
  • installFeature(name, version) は、名前および バージョンで 機能をインストールします
  • installFeature(name, noClean, noRefresh) は、バンドルのクリーニング なしに、すでにインストールされているバンドルを更新せずに、バンドルのクリーニングなしで機能をインストールします。
  • installFeature(name, version, noClean, noRefresh)' は、バンドルの障害発生時と、すでにインストールされているバンドルを更新せずに、バンドルをクリーンアップせずに「name and version 」で機能をインストールします
  • uninstallFeature(name)名前で 機能をアンインストールします。
  • uninstallFeature(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 console コマンドを使用して、リモートコンテナー のコンソールに接続します。

ssh:ssh コマンド構文

ssh:ssh -l username -P password -p port hostname

-l
リモートコンテナーへの接続に使用されるユーザー名。管理者権限を持つ 有効な JAAS ログインクレデンシャルを使用します。
-P
リモートコンテナーへの接続に使用されるパスワード。
-p
必要なコンテナーのリモートコンソールへのアクセスに使用される SSH ポート。デフォルト値は 8101 です。ポート番号の変更に関する情報は、「リモートアクセスのためのスタンドアロンコンテナーの設定」 を参照してください。
hostname
リモートコンテナーが実行されているマシンのホスト名。ホスト名の変更に関する詳細は、「リモートアクセスのためのスタンドアロンコンテナーの設定」 を参照してください。
警告

etc/users.properties ファイルでユーザー名とパスワードをカスタマイズすることが推奨されます。

注記

リモートコンテナーが SPARC インスタンス用の Oracle VM Server にデプロイされている場合、デフォルトの SSH ポート値 8101 は、論理ドメインマネージャーデーモンによってすでに占有されています。この場合、「リモートアクセスのためのスタンドアロンコンテナーの設定」 の説明に従って、コンテナーの SSH ポートを再設定する必要があります。

正しいコンテナーに接続していることを確認するには、Karaf コンソールプロンプトで shell:info を入力します。これにより、現在接続されているインスタンスに関する情報が返されます。

17.2.1.3. リモートコンソールからの切断

リモートコンソールから切断するには、ログアウト を入力するか、プロンプトで Ctrl+D を押します。

リモートコンテナーから切断され、コンソールは再びローカルコンテナーを管理できるようになります。

17.2.2. クライアントコマンドラインユーティリティーを使用したコンテナーへの接続

17.2.2.1. リモートクライアントの使用

リモートクライアントを使用すると、完全な Fuse コンテナーをローカルで起動せずに、リモート Red Hat Fuse コンテナーに安全に接続できます。

たとえば、同じマシン上でサーバーモードで実行中の Fuse インスタンスを迅速に接続するには、コマンドプロンプトを開いて( InstallDir/bin ディレクトリーにある) client[.bat] スクリプトを実行します。

client

通常は、リモートインスタンスに接続するためのホスト名、ポート、ユーザー名、およびパスワードを指定します。テストスイートなど、大規模なスクリプト内でクライアントを使用している場合は、以下のようにコンソールコマンドを追加できます。

client -a 8101 -h hostname -u username -p password shell:info

または、- p オプションを省略すると、パスワードを入力するよう求められます。

スタンドアロンコンテナーの場合は、管理者権限を持つ有効な 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 ファイルでデフォルトでコメントアウトされます。
  • ユーザー名とパスワードの管理/ 管理者の組み合わせを使用して ログインするデフォルトのユーザー名 /パスワード password。このログインの成功を可能にする対応する設定エントリーは、etc /users.properties ファイルでデフォルトでコメントアウトされます。

したがって、users.properties でデフォルトの管理者 /管理認証情報 をアンコメントして Karaf コンテナーで新しいユーザーを作成する場合は、認証情報を指定せずに bin/client ユーティリティーがログインできることがわかります。

重要

セキュリティー上の理由で、Karaf コンテナーが最初にインストールされるときに、Fuse はデフォルトのクレデンシャルを無効にします (コメントアウトして)。ただし、デフォルトのパスワードや SSH 公開鍵を変更せずにこれらのデフォルトクレデンシャルをアンコメントすると、Karaf コンテナにセキュリティーホールが発生します。これは実稼働環境では絶対に行わないでください。認証情報を指定せずに bin/client を使用してコンテナーにログインできる場合は、コンテナーが非セキュアであることを示しており、実稼働環境でこれを修正する手順が必要になります

17.2.2.3. リモートクライアントコンソールからの切断

コマンドを渡すためにリモートクライアントを使用する代わりに、リモートクライアントを使用してリモートコンソールを開いた場合は、リモートクライアントからコネクションを切断する必要があります。リモートクライアントのコンソールから切断するには、ログアウト するか、プロンプトで 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 JBoss 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 ファイルは、現在のプロジェクトの Project Object Model(POM)です。これには、現在のプロジェクトの構築方法の完全な説明が含まれています。pom.xml ファイルは完全に自己完結型ですが、頻繁には(より複雑な Maven プロジェクトの) 親 POM ファイルから設定をインポートできます。

プロジェクトのビルド後、pom.xml ファイルのコピーは自動的に生成された JAR ファイルの以下の場所に組み込まれます。

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 コンテナーのサポートが組み込まれています。これは、プロジェクトに Blueprint 設定ファイル OSGI-INF/blueprint/*.xml を含める だけで有効にできます。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 インデクサーログ

Maven Indexer プラグインがデプロイされたら、次のコマンドを使用して、Maven Indexer プラグイン設定に外部 Maven リポジトリーを追加します。

config:edit io.hawt.maven.indexer
config:proplist
config:propset repositories external repository
config:proplist
config:update

19.1. Log

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 file アペンダーを使用して 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 アペンダー
外部の アペンダーはデフォルトです。これは、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 オプションを使用して、(実行 用に)パターンを動的に変更することもできます。

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 コマンドはロガーのログレベルを設定します。

デフォルトでは、ルートロガーのログレベルが変更されます

karaf@root()> log:set DEBUG
karaf@root()> log:get
Logger                              │ Level
────────────────────────────────────┼──────
ROOT                                │ DEBUG
...

レベル 1 の後に logger 引数を使用して、特定のロガーを指定できます。

karaf@root()> log:set INFO my.logger
karaf@root()> log:get my.logger
Logger    | Level
-----------------
my.logger | INFO

level 引数は、すべての Log4j2 ログレベル(TRACE、DEBUG、INFO、WARN、ERROR、FATAL)を受け入れます。

また、特殊な 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.custom および my.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)は、ログイベントを、ログイベントを書き換えた後に別のアペンダーに転送します。

この種類のアペンダーは、アペンダー定義のアペンダー プロパティーを受け入れます。

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 属性

ルーティング アペンダーは、OSGi 指向のアペンダーで、MDC(マッピング診断コンテキスト)属性に基づいてログイベントを分割できます。

MDC では、ログイベントのさまざまなソースを区別できます。

ルーティング アペンダーは、デフォルトで 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 バンドルのフラグメントとしてアタッチすることです。

たとえば、My Appender を作成します。

public class MyAppender extends AppenderSkeleton {
...
}

次のようなマニフェストを含む OSGi バンドルとしてコンパイルしてパッケージ化します。

Manifest:
Bundle-SymbolicName: org.mydomain.myappender
Fragment-Host: org.ops4j.pax.logging.pax-logging-service
...

Apache Karaf システム フォルダーでバンドルをコピーします。system フォルダーは、標準の Maven ディレクトリーレイアウトを使用します(groupId/artifactId/version)。

etc/startup.properties 設定ファイルで、pax-logging-service バンドルの前にバンドルを一覧に定義します。

システムバンドルをリロードするには、クリーンな実行( データ フォルダー)で 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 つのログインモジュールがあります。

  • PropertiesLoginModuleetc/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: というプレフィックスが付けられます。このプレフィックスのないエントリーはユーザーです。

グループはロールのセットを定義します。デフォルトでは、admingroup は、グループ、管理 マネージャービューアーの ロール を定義します

これは、karaf ユーザーに admingroup で定義されているロールがあることを意味します。

20.1.1.1. コマンド

The 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)があります

インデックスは jaas:realm-manage コマンドによって使用され、管理するレルム/ログインモジュールを簡単に特定します。

20.1.1.1.2. jaas:realm-manage

The jaas:realm-manage command switch in realm/login module edit mode で、ログインモジュールでユーザー、グループ、およびロールを管理できます。

管理するレルムおよびログインモジュールを特定するには 、--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

The 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

The jaas:user-delete コマンドは、現在編集されたログインモジュールからユーザーを削除します。

karaf@root()> jaas:user-delete foo

jaas:user-add コマンドと同様に、jaas:update を使用して変更をコミットする必要があります(または jaas:cancel から rollback)。

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

The jaas:group-add コマンドは、現在編集されたログインモジュールでグループ(グループ)をユーザーに割り当てます。

karaf@root()> jaas:group-add karaf mygroup
20.1.1.1.7. jaas:group-delete

The jaas:group-delete コマンドは、現在編集されたログインモジュールのグループからユーザーを削除します。

karaf@root()> jaas:group-delete karaf mygroup
20.1.1.1.8. jaas:group-role-add

The jaas:group-role-add コマンドは、現在編集されたログインモジュールのグループにロールを追加します。

karaf@root()> jaas:group-role-add mygroup myrole
20.1.1.1.9. jaas:group-role-delete

The jaas:group-role-delete コマンドは、現在編集されたログインモジュールのグループからロールを削除します。

karaf@root()> jaas:group-role-delete mygroup myrole
20.1.1.1.10. jaas:update

The jaas:update コマンドは、ログインモジュールバックエンドで変更をコミットします。たとえば、PropertiesLoginModule の場合、jaas:update コマンドの実行後のみ etc/users.properties が更新されます。

20.1.1.1.11. jaas:cancel

The 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 y を true に設定すると、パスワードの暗号化が有効になります。

暗号化を有効にすると、ユーザーが最初にログインしたときにパスワードは暗号化されます。暗号化したパスワードの前に \{ CRYPT\} というプレフィックスが付けられます。パスワードを再暗号化するには、\{ CRYPT\} プレフィックスおよび接尾辞なしで、(etc /users.properties ファイル)パスワードをリセットできます。Apache Karaf は、このパスワードが不明確であることを検出し(\{ CRYPT\} でプレフィックスが付けられたため)、再度暗号化します。

etc/org.apache.karaf.jaas.cfg 設定ファイルを使用すると、高度な暗号化動作を定義できます。

  • encryption.prefix プロパティーは、パスワードを暗号化として「 flags」へのプレフィックスを定義します。デフォルトは \{ CRYPT\} です。
  • encryption.suffix プロパティーは、パスワードを暗号化として「 Flags」への接尾辞を定義します。デフォルトは \{ CRYPT\} です。
  • encryption.algorithm プロパティーは、暗号化に使用するアルゴリズム(digest)を定義します。使用できる値は MD2、MD5、SHA-1、SHA-256、SHA-384、SHA-512 です。デフォルトは MD5 です。
  • encryption.encoding プロパティーは、暗号化されたパスワードのエンコーディングを定義します。使用できる値は 16 進数 または base64 です。デフォルト値は 16 進数 です。

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(Access Lists)は etc/org.apache.karaf.command.acl.<scope>.cfg 設定ファイルで定義されています。ここで、& lt;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

ここで、function :list および feature:info コマンドは、viewer ロールを持つユーザーが 実行できますが、feature:install および feature:uninstall コマンドは admin ロールを持つユーザーのみが実行できます。admin グループのユーザーには viewer ロールもあるため、すべてを実行できることに注意してください。

Apache Karaf コマンド ACL は以下を使用してアクセスを制御できます (指定のコマンドスコープ内) 。

  • コマンド名の正規表現(name = roleなど)
  • コマンド名とオプションまたは引数値の正規表現(例: name[/.[0-9][0-9]+./] = role )は、引数の値が 100 を超える名前のみを実行します。

コマンド名とオプション/引数はいずれも、完全一致または正規表現の一致をサポートします。

デフォルトでは、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 コマンドを実行できます。他の機能 :* コマンドは、どのユーザーでも実行できます。
  • etc/org.apache.karaf.command.acl.jaas.cfg 設定ファイルは、jaas:* コマンド用の ACL を定義します。admin ロールが割り当てられたユーザーのみが、jaas:update コマンドを実行できます。other 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:edit、shell: exec、shell :new、および shell:java コマンドを実行します。他の シェル:* コマンドはどのユーザーでも実行できます。

これらのデフォルト ACL を変更し、追加のコマンドスコープのために独自の ACL を追加できます(例: Apache Karaf Cellar の場合は /etc /org .apache.karaf.command.acl.cluster.cfg )。Apache Camel …​

etc/system.properties の karaf.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 設定ファイルで定義されます。ここで、& lt;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 ロールを持つユーザーのみの system バンドルの 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 は、ビューアー ロールの あるユーザーの 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 は、manager ロールを持つユーザーに対してのみ gc 操作の呼び出しを制限します。
  • 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) 現在のユーザーが objectNamefalse で MBean を呼び出しできる場合、true を返します。
  • canInvoke(objectName, methodName) は、現在のユーザーが objectName やfalse で MBean で操作 methodName を呼び出せる 場合 true を返します。
  • canInvoke(objectName, methodName, argumentTypes) は、現在のユーザーが object Name やfalse の MBean の引数型 argumentTypes の配列で操作 method Name を呼び出せる 場合、true を返します。
  • canInvoke(bulkQuery) は、Invoketrue または false の場合、一括処理の各操作に含まれるテーブルデータ を返します。

20.1.6. セキュリティープロバイダー

一部のアプリケーションでは、特定のセキュリティープロバイダー (BouncyCastle など) が利用可能でなければなりません。

JVM は、このような jar の使用に制限を課します。それらは署名され、ブートクラスパスで利用可能でなければなりません。

これらのプロバイダーをデプロイする 1 つの方法として、JRE フォルダーを $JAVA_HOME/jre/lib/ext に配置し、セキュリティーポリシーの設定($JAVA_HOME/jre/lib/security/java.security)を変更して、このようなプロバイダーを登録することです。

このアプローチは正常に動作しますが、グローバルな効果があり、それに応じてすべてのサーバーを設定する必要があります。

Apache Karaf は、追加のセキュリティープロバイダーを設定する簡単な方法を提供します。* provider 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*