6 OCMS Parlay X Web Services

この章では、アプリケーション開発用のParlay X 2.0 Presence Web Servicesインタフェースに対するOCMSのサポートについて説明します。Webサービスは、Webサービスのユーザーにかわって通知を公開、サブスクライブおよびリスニングするプレゼンス・ネットワーク・エージェントとして機能します。この章の内容は次のとおりです。

概要
Webサービスのインストール
集約プロキシのインストール
集約プロキシを使用したWebサービスの構成
Presence Web Servicesインタフェースの説明
Presence Web Servicesインタフェースの使用
OCMS Parlay X Presenceカスタム・エラー・コード

概要

OCMSは、「Open Service Access, Parlay X Web Services, Part 14, Presence ETSI ES 202 391-14」仕様で定義されたParlay X Presence Web Serviceのパート14をサポートします。OCMS Parlay X Web Serviceは、「Open Service Access, Mapping of Parlay X Web Services to Parlay/OSA APIs, Part 14, Presence Mapping, Subpart 2, Mapping to SIP/IMS Networks, ETSI TR 102 397-14-2」仕様に従って、Parlay X Web ServiceをSIP/IMSネットワークにマップします。

注意:

Webサービスの同期性により、Webサービスからコールバックを受信するには、クライアントはWebサービス・コールバック・インタフェースを実装する必要があります。現時点では、必要なインタフェースは、「Open Service Access, Parlay X Web Services, Part 14, Presence ETSI ES 202 391-14」で説明されているPresenceNotificationインタフェースです。

この実装はほとんどのWebサービス・アーキテクチャにとって一般的でも実際的でもないため、PresenceNotificationインタフェースは現在サポートされていません。

Presence Web Serviceは、SIP/SIMPLEプロトコル・インタフェースを使用してIMSプレゼンス・ネットワーク要素と直接通信し、JSR-32 UACフレームワークを使用して、SIPネットワークと通信します。

Presence Web ServiceをホスティングするHTTPサーバーは、プレゼンス・ネットワーク・エージェントまたはParlay XからSIPへのゲートウェイです。

Webサービスのインストール

Webサービスは、標準.earファイルとしてパッケージ化され、他のWebサービスと同じようにEnterprise Managerを使用してデプロイできます。.earファイルには、2つのインタフェースを実装する2つの.warファイルが含まれています。WebサービスがPresenceサーバーと同じサーバーにデプロイされる場合、Presenceサーバーの子アプリケーションにする必要があります。

集約プロキシのインストール

集約プロキシは、標準.earファイルとしてパッケージ化され、Enterprise Managerからデプロイできます。2つの要件があります。

アプリケーション名をaggregationproxyearにする必要があります。
親アプリケーションをsubscriberdataservicesにする必要があります。集約プロキシは、subscriberdataservicesの認証機能を使用して、Webサービスを認証します。

集約プロキシを使用したWebサービスの構成

Webサービスは、別のエンティティが認証を実行する信頼されたドメインで動作します。Webサービスを認証し、サービスのユーザーを識別するために、OCMSでは集約プロキシを使用して「3GPP TS 33.222 Generic Authentication Architecture (GAA); Access to network application functions using Hypertext Transfer Protocol over Transport Layer Security (HTTPS)」で定義されたHTTP X-3GPP-ASSERTED-IDENTITYヘッダーを挿入します。

Webサービス・デプロイメント・サーバーを定義するには、次のようにします。

集約プロキシ用のEnterprise Managerページを開きます。
WebServiceHostとWebServicePortをWebサービス・デプロイメント・サーバーのホストとポートに構成します。
XCAPHost、XCAPPortおよびXCAPRootをXDMSの場所とパラメータに構成します。

Presence Web Servicesインタフェースの説明

Presence Web Servicesは、3つのインタフェースで構成されます。

PresenceConsumer: ウォッチャはこれらのメソッドを使用して、プレゼンス・データを取得します（表6-1）。
PresenceNotification: プレゼンス・コンシューマ・インタフェースは、このインタフェースで定義されたクライアント・コールバックを使用して、通知を送信します。OCMSは現在PresenceNotificationをサポートしていません（表6-2）。
PresenceSupplier: プレゼンティティは、これらのメソッドを使用して、プレゼンス・データを提供し、ウォッチャによるデータへのアクセスを管理します（表6-3）。

表6-1 PresenceConsumerインタフェース

操作	説明
subscribePresence	Webサービスは、プレゼンス・サーバーにSUBSCRIBEを送信します。
getUserPresence	プレゼンティティのステータス変更がSIP NOTIFYを通して非同期でWebサービスに送られるため、キャッシュされたプレゼンス・ステータスを返します。Webサービスは、実際にはWebサービス・クライアントではなくサブスクリプションを持ちます。
startPresenceNotification	サポートされていません。
endPresenceNotification	サポートされていません。

表6-2 PresenceNotificationインタフェース

操作	説明
statusChanged	サポートされていません。
statusEnd	サポートされていません。
notifySubscription	サポートされていません。
subscriptionEnded	サポートされていません。

表6-3 PresenceSupplierインタフェース

操作	説明
publish	SIP PUBLISHに直接マップします。
getOpenSubscriptions	ウォッチャがこのプレゼンス・データをサブスクライブするかどうかをチェックするために、プレゼンティティ（サプライヤ）によってコールされます。このメソッドにマップされるSIPメッセージはありません。Webサービス・サーバーで現在保留中のサブスクリプションを返します。
updateSubscriptionAuthorization	サプライヤはこのメソッドを使用して、オープン状態の保留中のサブスクリプションに応答します。プレゼンスルール・ドキュメントを更新するために、XCAP PUTメッセージがXDMSサーバーに送信されます。
getMyWatchers	Webサービス・サーバーからウォッチャのローカル・リストを取得します。
getSubscribedAttributes	Webサービス・サーバーからサブスクライブ済属性のローカル・リストを取得します。現在は、Activityのみを返します。
blockSubscription	XDMSサーバー上のXCAPドキュメントを変更して（ブロック・リストにウォッチャを入れて）、Webサービス・サーバーでのウォッチャ・サブスクリプションを終了させます。

Presence Web Servicesインタフェースの使用

この項では、インタフェースでの各操作の使用方法を、コード例を使用して説明します。

インタフェース: PresenceConsumer、操作: subscribePresence

これは、このインタフェースで別の操作を使用する前に、アプリケーションがコールする必要がある最初の操作です。次の2つの目的を果します。

Webサービスが、現在のHTTPセッションとユーザーを関連付けられるようにします。
少なくとも1つのプレゼンティティ（SUBSCRIBEプレゼンス・イベント）をサブスクライブして、このインタフェースで他のすべての操作にコンテキストを提供します。

コード例

// Setting the attribute to activity
PresenceAttributeType pa = PresenceAttributeType.Activity;
PresenceAttributeType[] pat = new PresenceAttributeType[]{pa};

// These inputs are required but not used.
SimpleReference sr = new SimpleReference();
sr.setCorrelator("unused_correlator");
sr.setInterfaceName("unused_interfacename");
sr.setEndpoint(new URI ("http://unused.com"));

// Calling the web service
consumer.subscribePresence (new URI
("sip.presentity@test.example.com") , pat, "unused", sr);

インタフェース: PresenceConsumer、操作: getUserPresence

サブスクライブ済のプレゼンティティのプレゼンスを取得するには、この操作をコールします。その人がオフラインの場合はActivityNoneが返され、PresenceAttribute.noteにハードステートが書き込まれます。ActivityOtherが返された場合、OtherValueフィールドにアクティビティの説明が返されます。

Nameフィールドが「ServiceAndDeviceNote」と等価である場合、OtherValueは、サービス・メモとデバイス・メモの結合したものです。プレゼンティティが複数のクライアントに記録される場合、複数の「ServiceAndDeviceNote」が存在する可能性があります。

コード例

PresenceAttributeType pat = new
  PresenceAttributeType(){PresenceAttributeType.Activity};
PresenceAttribute[] resultPA =
  consumer.getUserPresence(new URI(presentity),pat);
for (int i = 0; i < resultPA.length; i++){
  PresenceAttribute pa = resultPA[i];
  // Check to see if it is an activity type.
  if (pa.getTypeAndValue().getUnionElement() ==
              PresenceAttributeType.Activity){
     // Get the presence status.
     System.out.println("Activity: " +
         pa.getTypeAndValue().getActivity().toString());
     // Get the customized presence note.
     if (pa.getNote().length() > 0){
        System.out.println("Note: " + pa1.getNote());
    }
  }
  // If this is of type Other, then we need to extract
  // different type of information.
  if (pa.getTypeAndValue().getUnionElement() ==
              PresenceAttributeType.Other){
    // This is "ActivityOther", a custom presence status.
    if (pa.getTypeAndValue().getOther()
             .getName().compareToIgnoreCase("ActivityOther") == 0){
   System.out.println("Other Activity->" +
          pa.getTypeAndValue().getOther().getValue() + "\n");
 } else {
    // Currently, the only other value beside ActivityOther is
    // "ServiceAndDeviceNote" which is the service note +
    // device note.
    System.out.println("Combined Note->" +
        pa.getTypeAndValue().getOther().getValue() + "\n");
    }
  }
}

インタフェース: PresenceSupplier、操作: publishおよびOracle固有の"Unpublish"

これは、このインタフェースで別の操作を使用する前に、アプリケーションがコールする必要がある最初の操作です。次の3つの目的を果します。

Webサービスが、現在のHTTPセッションとユーザーを関連付けられるようにします。
ユーザーのプレゼンス・ステータスを公開します。
Webサービスがウォッチャのリクエストを追跡できるように、ウォッチャ情報をサブスクライブします。

PUBLISHを実行する際、関与する属性が3つあります。これらの属性をPresenceAttribute構造に設定して、PUBLISHメソッドに渡すことができます。

カスタマイズ・メモのあるプレゼンス・ステータス: これはOracle Communicatorの「My Presence」テキスト・ボックスに構成されたカスタマイズ・メモです。<note>要素は、プレゼンス情報データ・フォーマット（PIDF）XMLファイルの<person>要素に含まれています。
デバイス・メモ: Oracle Communicatorによって暗黙的に挿入されます。またはWebサービスから挿入されます。<note>要素は、プレゼンス情報データ・フォーマット（PIDF）XMLファイルの<device>要素に含まれています。
サービス・メモ: Oracle Communicatorプリファレンスの「Presence」タブに構成されています。<note>要素は、プレゼンス情報データ・フォーマット（PIDF）XMLファイルの<tuple>要素に含まれています。

コード例

// PresenceAttribute contains presence status and note.
typeValue.setUnionElement(PresenceAttributeType.Activity);
typeValue.setActivity(activity);
paActivity.setTypeAndValue(typeValue);
// Setting the customized note here.
paActivity.setNote(activityNote);
paActivity.setLastChange(dateTime);

// Create the PresenceAttribute containing device note.
AttributeTypeAndValue typeValueOther = createATV();
PresenceAttribute paOther = new PresenceAttribute();
// Device note is carried in a PresenceAttributeType.Other
typeValueOther.setUnionElement(PresenceAttributeType.Other);
// Set the name to "DeviceNote" to indicate the value
// should be used as device note.
other.setName("DeviceNote");
other.setValue(deviceName);
typeValueOther.setOther(other);
paOther.setTypeAndValue(typeValueOther);
// The note is not used. Can be anything.
paOther.setNote("OracleExtension");
paOther.setLastChange(dateTime);

// Create the PresenceAttribute containing service note.
AttributeTypeAndValue typeValueOther1 = createATV();
PresenceAttribute paOther1 = new PresenceAttribute();
// Service note is carried in another
// PresenceAttributeType.Other
typeValueOther1.setUnionElement(PresenceAttributeType.Other);
OtherValue other1 = new OtherValue();
// Set the name to "ServiceNote" to indicate the value
// should be used as device note.
other1.setName("ServiceNote");
other1.setValue(serviceName);
typeValueOther1.setOther(other1);
paOther1.setTypeAndValue(typeValueOther1);
// The note is not used. Can be anything.
paOther1.setNote("OracleExtension");
paOther1.setLastChange(dateTime);

//Unpublish Functionality Implemented by OCMS
//To perform an "Unpublish", set OtherValue to (Expires, 0)
//OtherValue other = new OtherValue();
//other.setName("Expires");
//other.setValue(0);
//typeValue.setOther (other);
//typeValue.setUnionElement(PresenceAttributeTypeOther);

paArray = new PresenceAttribute[]{paActivity,paOther,paOther1};

// Calling the publish method by passing the PresenceAttribute
// array containing the presence status, device note and service
// note.
publish(paArray);

インタフェース: PresenceSupplier、操作: getOpenSubscriptions

この操作では、ウォッチャ・リストに入れる新しいリクエストのリストを取得します。

コード例

SubscriptionRequest[] srArray = getOpenSubscriptions();
for (SubscriptionRequest sr:srArray) {
    System.out.println(sr.getWatcher() .toString());
}

インタフェース: PresenceSupplier、操作: updateSubscriptionAuthorization

この操作では、ブロック・リストまたは許可リストにウォッチャを入れることができます。

コード例

 //You always pass in Activity
pp.set.PresenceAttribute(PresenceAttributeType.Activity);
updateSubscriptionAuthorization(new URI("sip:allow@test.example.com"),
new PresencePermission[]{pp});
PresencePermission pp = new PresencePermission();
pp.setDecision(true);
//Put the user on the allow list

インタフェース: PresenceSupplier、操作: getMyWatchers

この操作では、許可リストのウォッチャのリストを取得します。

コード例

 URI[] uris;
uris = getMyWatchers();
for (URI uri:uris)
    System.out.println(uri.toString());

インタフェース: PresenceSupplier、操作: getSubscribedAttributes

この操作では、PresenceTypeAttribute.Activityの1つの項目のみが返されます。既存のサブスクリプションがない場合は、例外がスローされます。

コード例

PresenceAttributeType[] pat =
getSubscriberdAttributes("sip:watcher@test.example.com");

インタフェース: PresenceSupplier、操作: blockSubscription

この操作では、ウォッチャがブロック・リストに入れられます。

コード例

blockSubscription(new URI("sip:block.this.watcher@test.example.com"));

OCMS Parlay X Presenceカスタム・エラー・コード

OCMSでは、Parlay Xの標準例外に2つの拡張を導入しています。

PresencePolicyExceptionはPolicyExceptionを拡張します。
PresenceServiceExceptionはServiceExceptionを拡張します。

表6-4と表6-5は、エラー・コードおよび関連するエラー・メッセージの説明です。

表6-4 OCMS Parlay X Presenceカスタム・エラー・コード: PresencePolicyException

エラー・コード	エラー・メッセージ
OPOL0001	Watcher is on the block, polite-block or pending list.

表6-5 OCMS Parlay X Presenceカスタム・エラー・コード: PresenceServiceException

エラー・コード	エラー・メッセージ
PRES0001	Invalid result from XDMS server.
PRES0002	Invalid HTTP session data.
PRES0003	Invalid URI.
PRES0004	Peer unavailable.
PRES0005	Unknown host.
PRES0006	Service unavailable.
PRES0007	Internal error.
PRES0008	User unauthenticated.