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

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

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

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

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

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

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

たとえば、ステートレスの 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;
    }
    ...
}

たとえば、ステートフルな 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;
    }
    ...
}

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

(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)"/>

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

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

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

たとえば、以下の 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 引数を取ります。