| Oracle® WebLogic Communication Services 開発者ガイド 11g リリース 1 (11.1.1) B55506-01 |
|
 戻る |
 次へ |
この章では、アプリケーション開発用の Parlay X 2.0 Presence Web Services インタフェースのサポートについて説明します。 Web サービスは、Web サービスのユーザに代わって通知をパブリッシュ、サブスクライブおよびリスンできるプレゼンス ネットワーク エージェントとして機能します。 この章の内容は以下のとおりです。
OWLCS では、「Open Service Access, Parlay X Presence Web Services, Part 14, Presence ETSI ES 202 391-14」仕様で定義された Parlay X Presence Web Service のパート 14 をサポートします。 OWLCS Parlay X Web Service は、「Open Service Access, Mapping of Parlay X Presence 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サービスを SIP/IMS ネットワークにマップします。
Presence Web Service をホストする HTTP サーバーは、プレゼンス ネットワーク エージェントまたはParlay X から SIP へのゲートウェイです。
Web サービスは標準の .ear ファイルとしてパッケージ化されており、他の Web サービスと同様に管理コンソールでデプロイできます。 .ear ファイルには、2 つのインタフェースを実装する 2 つの .war ファイルが含まれています。Web サービスは Oracle SDP プラットフォーム、クライアント、およびプレゼンス共通の共有ライブラリを使用します。
Presence Supplier Web サービスにコンフィグレーション可能な以下の 4 つの Mbean 属性があります。
SIPOutboundProxy : SIP メッセージの発信プロキシの SipURI。 空文字列の場合、発信プロキシは存在しません。 (例 : sip:127.0.0.1:5060; lr;transport=tcp)。
PublicXCAPRootUrl : Presence Server のデプロイ先の URI。 この属性は、XDMS に 保存されているプレゼンス ルールの更新に使用します。 (例 : http://127.0.0.1:8001/services/)
Expires : プレゼンティティによるパブリッシュが期限切れになるまでの時間を秒単位で設定します。 デフォルト値は 3600 (1 時間) です。
SessionTimeout : HTTP セッションがタイムアウトするまでの時間を秒単位で設定します。 タイムアウトしたすべてのセッションのデータが破棄されます。
Presence Consumer にコンフィグレーション可能な 3 つの Mbean 属性があります。
SIPOutboundProxy : SIP メッセージの発信プロキシの SipURI。 空文字列の場合、発信プロキシは存在しません。 (例 : sip:127.0.0.1:5060; lr;transport=tcp)。
Expires : ウォッチャによるサブスクライブが期限切れになるまでの時間を秒単位で設定します。デフォルト値は 3600 (1 時間) です。
SessionTimeout : HTTP セッションがタイムアウトするまでの時間を秒単位で設定します。 タイムアウトしたすべてのセッションのデータが破棄されます。
Presence Web Services は以下の 3 つのインタフェースで構成されます。
PresenceConsumer : ウォッチャはこれらのメソッドを使用して、プレゼンス データを取得します (表 8-1)。
PresenceNotification : プレゼンス コンシューマ インタフェースは、このインタフェースで定義されたクライアント コールバックを使用して通知を送信します (表 8-2)。
PresenceSupplier : プレゼンティティは、これらのメソッドを使用してプレゼンス データをパブリッシュし、そのウォッチャによるデータへのアクセスを管理します (表 8-3)。
表 8-1 PresenceConsumer インタフェース
| 操作 | 説明 |
|---|---|
|
subscribePresence |
Web サービスは、プレゼンス サーバに SUBSCRIBE を送信します。 |
|
getUserPresence |
プレゼンティティのステータス変更が、SIP NOTIFY によって非同期で Web サービスに送信されるため、キャッシュされたプレゼンス ステータスを返します。Web サービスに実際に存在するのは、Web サービス クライアントではなくサブスクリプションです。 |
|
startPresenceNotification |
プレゼンティティによってプレゼンスのステータスまたはプレゼンス ルール ドキュメントが変更されるたびに Web サービス クライアントが通知を非同期に受信できるようにします。 |
|
endPresenceNotification |
Web サービス クライアントによる通知の非同期受信を無効にします。 |
表 8-2 PresenceNotification インタフェース
| 操作 | 説明 |
|---|---|
|
statusChanged |
非同期操作は、通知を要求した属性が変更されると、Web サービスによって呼び出されます。 |
|
statusEnd |
このメソッドは、コリレータによって識別される通知期間が終了したときに呼び出されます。 エラーが発生した場合や endPresenceNotification を明示的に呼び出した場合、このメソッドは呼び出されません。 |
|
notifySubscription |
この非同期メソッドは、プレゼンティティが保留中のサブスクリプションを処理したことをウォッチャに通知します。 |
|
subscriptionEnded |
この非同期操作は Web サービスによって呼び出され、サブスクリプションが終了したことをウォッチャに通知します。 |
表 8-3 PresenceSupplier インタフェース
| 操作 | 説明 |
|---|---|
|
publish |
SIP PUBLISH に直接マップします。 |
|
getOpenSubscriptions |
ウォッチャがプレゼンス データをサブスクライブするかどうかを確認するために、プレゼンティティ (サプライヤ) によって呼び出されます。このメソッドにマップされる SIP メッセージはありません。Web サービス サーバで現在保留中のサブスクリプションを返します。 |
|
updateSubscriptionAuthorization |
サプライヤはこのメソッドを使用して、オープン状態の保留中のサブスクリプションに応答します。XCAP PUT メッセージは、presence-rule ドキュメントを更新するために XDMS サーバに送信されます。 |
|
getMyWatchers |
Web サービス サーバからウォッチャのローカル リストを取得します。 |
|
getSubscribedAttributes |
Web サービス サーバからサブスクライブされた属性のローカル リストを取得します。現在は、Activity のみを返します。 |
|
blockSubscription |
XDMS サーバーで XCAP ドキュメントを変更して (ブロック リストにウォッチャを追加して)、Web サービス サーバーでのウォッチャ サブスクリプションを終了させます。 |
ここでは、インタフェースの各操作の使用方法を、コード例を使用して説明します。
これは、このインタフェースで別の操作を使用する前に、アプリケーションが呼び出す必要のある最初の操作です。この操作は次の 2 つの目的を果します。
Web サービスで、現在の HTTP セッションとユーザを関連付けられるようにします。
少なくとも 1 つのプレゼンティティ (SUBSCRIBE プレゼンス イベント) をサブスクライブして、このインタフェースで他のすべての操作にコンテキストを提供します。
// アクティビティの属性を設定する
PresenceAttributeType pa = PresenceAttributeType.ACTIVITY;
List<PresenceAttributeType> pat = new ArrayList<PresenceAttributeType>();
pat.add(pa);
SimpleReference sr = new SimpleReference();
sr.setCorrelator("");
sr.setInterfaceName("");
sr.setEndpoint("");
consumer.subscribePresence ("sip.presentity@test.example.com" , pat, "unused", sr);
サブスクライブされたプレゼンティティのプレゼンスを取得するには、この操作を呼び出します。そのユーザーがオフラインの場合、ActivityNone が返され、PresenceAttribute.note にハードステートが書き込まれます。ActivityOther が返される場合、OtherValue フィールドにアクティビティの説明が返されます。
Name フィールドの値が "ServiceAndDeviceNote" である場合、OtherValue は、サービス メモとデバイス メモを結合したものになります。プレゼンティティが複数のクライアントに記録される場合、複数の ServiceAndDeviceNote が存在する可能性があることに注意してください。
PresenceAttributeType pat =
PresenceAttributeType.ACTIVITY;
List<PresenceAttribute> result =
consumer.getUserPresence(presentity, pat);
for (PresenceAttribute pa : result) {
// アクティビティ タイプであるかどうかを確認する。
if (pa.getTypeAndValue().getUnionElement() ==
PresenceAttributeType.ACTIVITY){
// プレゼンスのステータスを取得する。
System.out.println("ACTIVITY: " +
pa.getTypeAndValue().getActivity().toString());
// カスタマイズしたプレゼンス メモを取得する。
if (pa.getNote().length() > 0){
System.out.println("Note: " + pa.getNote());
}
}
// タイプが OTHER の場合、
// 別のタイプの情報を抽出する必要がある。
if (pa.getTypeAndValue().getUnionElement() ==
PresenceAttributeType.OTHER){
// タイプがカスタム プレゼンス ステータス、"Activity_Other" の場合。
if (pa.getTypeAndValue().getOther()
.getName().compareToIgnoreCase("ACTIVITY_OTHER") == 0){
System.out.println("Other Activity->" +
pa.getTypeAndValue().getOther().getValue() + "\n");
} else {
// 現在、ACTIVITY_OTHER 以外の値は
// サービス メモ + デバイス メモを表す
// "ServiceAndDeviceNote" のみ。
System.out.println("Combined Note->" +
pa.getTypeAndValue().getOther().getValue() + "\n");
}
}
}
この非同期操作は、通知を要求した属性が変更されると、Web サービスによって呼び出されます。
public void
statusChanged(String context, String correlator, String uri,
List<PresenceAttribute> presenceAttributes) {
System.out.println("statusChanged Called:-");
System.out.println("Context = " + context);
System.out.println("Correlator = " + correlator);
System.out.println("Presentity = " + uri);
}
このメソッドは、コリレータによって識別される通知期間が終了したときに呼び出されます。 エラーが発生した場合や endPresenceNotification を明示的に呼び出した場合、このメソッドは呼び出されません。
この非同期メソッドは、プレゼンティティが保留中のサブスクリプションを処理したことをウォッチャに通知します。
public void notifySubscription(String context, String uri,
List<PresencePermission> presencePermissions) {
System.out.println("notifySubscription Called:-");
System.out.println("Context = " + context);
System.out.println("Uri = " + uri);
if (presencePermissions.size() > 0){
for (PresencePermission p:presencePermissions){
System.out.println("Permission " +
p.getPresenceAttribute().value()
+ "->" + p.isDecision());
}
}
}
この非同期操作は Web サービスによって呼び出され、サブスクリプションが終了したことをウォッチャに通知します。
これは、このインタフェースで別の操作を使用する前に、アプリケーションが呼び出す必要のある最初の操作です。この操作は次の 3 つの目的を果します。
Web サービスで、現在の HTTP セッションとユーザを関連付けられるようにします。
ユーザのプレゼンス ステータスをパブリッシュします。
Web サービスがウォッチャ要求を追跡できるように watcher-info をサブスクライブします。
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 pa = new PresenceAttribute();
OtherValue other = new OtherValue();
//名前を "DeviceNote" に設定して、デバイス メモに使用する値であることを示す。
other.setName("DeviceNote");
other.setValue("Device Name");
//ServiceNote などに別の値を定義することも可能
CommunicationValue comm = new CommunicationValue();
AttributeTypeAndValue typeValue = new AttributeTypeAndValue();
typeValue.setUnionElement(PresenceAttributeType.ACTIVITY);
typeValue.setActivity(activity);
typeValue.setPlace(PlaceValue.PLACE_NONE);
typeValue.setPrivacy(PrivacyValue.PRIVACY_NONE);
typeValue.setSphere(SphereValue.SPHERE_NONE);
typeValue.setCommunication(comm);
typeValue.setOther(other);
pa.setTypeAndValue(typeValue);
String note = "My Note";
pa.setNote(note);
XMLGregorianCalendar dateTime = null;
dateTime = DatatypeFactory.newInstance().newXMLGregorianCalendar(new GregorianCalendar());
pa.setLastChange(dateTime);
List<PresenceAttribute> pat = new ArrayList<PresenceAttribute>();
pat.add(pa);
supplier.publish(pat);
//アンパブリッシュするには、OtherValue に (Expires, 0) を設定する
OtherValue other = new OtherValue();
other.setName("Expires");
other.setValue(0);
この操作では、ブロック リストまたは許可リストにウォッチャを追加することができます。
表 8-4 と 表 8-5 では、エラー コードと関連するエラー メッセージについて説明しています。
表 8-4 OWLCS Parlay X Presence のカスタム エラー コード : PolicyException
| エラー コード | エラー メッセージ |
|---|---|
|
POL0001 |
General Policy Exception (一般的なポリシー例外)。この例外には以下のタイプがあります。 SDP20201 Watcher is on the block, polite-block or pending list (ウォッチャがブロック、polite-block、または保留リストに存在する)。 SDP20202 Subscription is pending (サブスクリプションは保留中)。 |
|
POL0002 |
Privacy verification failed for address <address>, request is refused (アドレス <アドレス> のプライバシーの確認が失敗し、要求が拒否された)。 |
|
POL0003 |
Too many addresses specified in message part (メッセージ パートに指定したアドレスが多すぎる)。 |
表 8-5 OWLCS Parlay X Presence のカスタム エラー コード : ServiceException
| エラー コード | エラー メッセージ |
|---|---|
|
SVC0001 |
General Service Exception (一般的なサービス例外)。この例外には以下のタイプがあります。 SDP20101 Invalid result from XDMS server (XDMS サーバから無効な結果が返された)。 SDP20102 Invalid HTTP session data (無効な HTTP セッション データ)。 SDP20103 Invalid uri (無効な URI)。 SDP20104 Peer unavaliable (ピアが使用不可状態)。 SDP20105 Unknown host (不明なホスト)。 SDP20106 Service not avaliable (サービスが使用不可状態)。 SDP20107 Internal error (内部エラー)。 SDP20108 User unauthenticated (ユーザが認証されていない)。 |
|
SVC0002 |
Invalid input value for message part (メッセージ パートに入力した値が無効)。 |
|
SVC0003 |
Invalid input value for message part, valid values are <values> (メッセージ パートに入力した値が無効。有効な値は <値>)。 |
|
SVC0004 |
No valid addresses provided in message part (メッセージ パートに有効なアドレスが指定されていない)。 |
|
SVC0005 |
Correlator <correlator> specified in message part is a duplicate (メッセージ パートに指定したコリレータ <コリレータ> が重複している)。 |
|
SVC0220 |
No subscription request from watcher <watcher> for attribute <attribute> (属性 <属性> に対するウォッチャ <ウォッチャ> からのサブスクリプション要求が存在しない)。 |
|
SVC0221 |
<watcher> is not a watcher (<ウォッチャ> はウォッチャではない)。 |
Contact Management API (CMAPI) は、resource-lists (「バディ リスト」とも呼ばれる) および presence-rules ドキュメントを操作する API です。 この高度な API を使用して、ユーザに代わってバディ リストのバディを追加または削除したり、他のユーザ (ウォッチャ) にプレゼンス情報の参照を許可またはブロックしたりするなどの操作を行うことができます。 CMAPI には、XDMS (XML Document Management Server) に保存されたリソースをクエリおよび操作する機能があります。 CMAPI は Web サービス : XML Document Management Client (XDMC) サービスと、oracle.sdp.client 共有ライブラリに含まれる Java クライアント スタブで構成されます。
CMAPI は oracle.sdp.client 共有ライブラリに含まれます。 このライブラリが使用可能であれば、パッケージをインポートして API を使用できます。
import oracle.sdp.presence.integration.Buddy; import oracle.sdp.presence.integration.BuddyListManager; import oracle.sdp.presence.integration.BuddyListManagerFactory; import oracle.sdp.presence.integrationimpl.BuddyListManagerImpl;
BuddyListManagerFactory はシングルトン パターンに従い、ファクトリのインスタンスが XDMS/XDMC の組み合わせごとに 1 つのみ存在します。 そのため、BuddyListManagerFactory を作成する場合は、ドキュメントのダウンロード元となる XDMS に XCAP のルート URL を指定し、クライアント側で動作している XDM クライアント サービスにも URL を指定する必要があります。XDMC サービスの URL を渡すには、BindingProvider.ENDPOINT_ADDRESS_PROPERTY プロパティを使用します。 このような XCAP のルート URL と XDM クライアント サービス エンドポイントの組み合わせごとに生成可能な BuddyListManagerFactory インスタンスは 1 つのみです。 そのため、異なる XDMS/XDMC サービスの組み合わせを示すファクトリを作成することができます。
例 8-1 BuddyListManagerFactory のインスタンスの取得
// XDMS を示す URI を作成する。
URI xcapRoot = new URI("http://localhost:8001/services");
// XDM クライアント Web サービスが存在する場所。
String wsUrl = "http://localhost:8001/XdmClientService/services/XdmClient";
String sWsSecurityPolicy = new String[]{"oracle/wss11_saml_token_with_message_protection_client_policy"};
Map<String, Object> params = new HashMap<String,Object>();
params.put(BindingProvider.ENDPOINT_ADDRESS_PROPERTY, wsUrl);
params.put(BindingProvider.USERNAME_PROPERTY, "alice");
params.put(ParlayXConstants.POLICIES, sWsSecurityPolicy);
// Obtain the instance to the factory
BuddyListManagerFactory factory = BuddyListManagerFactory.getInstance(xcapRoot, params);
例 8-1 に、localhost:8001/ サービスの XCAP ルートを示すファクトリへの参照を取得する方法を示します。 このファクトリで実行する各操作は、ここで指定した XCAP ルートのコンテキストに存在します。 そのため、特定ユーザの BuddyListManager を作成する場合、その BuddyListManager の XCAP ルートは BuddyListManager の作成に使用したファクトリのいずれかになります。
BuddyListManager (BLM) は特定ユーザの代わりに操作を実行する機能であることを理解しておくことが重要です。 したがって、たとえばユーザ Alice の BLM を作成した場合、この BLM は Alice の代理で Alice のドキュメントを操作します。 例 8-2 に、前節で作成したファクトリを使用して Alice の BLM を作成する方法を示します。
例 8-2 ユーザ Alice の BuddyListManager の取得
URI user = new URI("sip:alice@example.com");
Map<String, Object> params = new HashMap<String,Object>();
params.put(XDMClientFactory.PROP_ASSERTED_IDENTITY, assertedId);
BuddyListManager manager = factory.createBuddyListManager(user, params);
例 8-2 に、SIP アドレス sip:alice@example.com を指定してユーザ Alice の BLM を作成する方法を示します。 他のユーザのバディ リストおよびプレゼンス ルール ドキュメントを操作しなければならない場合は、適切な SIP アドレスを指定して別の BLM を作成する必要があります。
バディ リストにバディを追加するには、バディを作成し、そのバディに必要な情報を設定してから、BLM を使用してバディ リストにバディを追加します。 例 8-3 に、Alice を表す BLM を使用して、Alice の新しいバディとして Bob を追加し、更新されたリストを取得する方法を示します。
例 8-3 バディ リストへの Alice の新しいバディの追加
URI uri = new URI("sip:bob@example.com");
Buddy bob = manager.createBuddy(uri);
// 追加情報を設定する (省略可)。
manager.setDisplayname("Bobby");
VCard vcard = bob.getVCard();
vcard.setCity("San Francisco");
vcard.setCountry("USA");
// VCard をバディに設定することが重要
bob.setVCard(vcard);
// BLM を使用してバディ情報を更新する
manager.updateBuddy(bob);
// 更新されたバディリストを取得する
List<Buddy> buddies = manager.getBuddies();
例 8-3 に、新しいバディ Bob を作成し、Alice の BLM を使用してこのバディを Alice のバディ リストに追加する方法を示します。 アドレスなど、ユーザ Bob の詳細情報を追加するには、Bob の Vcard 情報にアクセスして適切なプロパティを設定します。
|
注意 : getVCard() メソッドで返されるのは VCard のクローンであるため、対象バディに対して setVCard() メソッドを呼び出して情報を更新する必要があります。 |
バディの削除方法は、バディを追加する場合とほぼ同様です。removeBuddy メソッドに削除するバディを渡します。 複数のバディを削除する場合は removeBuddies メソッドに削除するバディのリストを渡します。 例 8-4 に、Aliceのバディ リストから Bob を削除する方法を示します。
BuddyListException は基本例外です。プログラムで特定の例外の登録を設定しなければ、この例外でキャッチされます。
XDMException は、リモート XDMS との通信に関するすべての例外の基本例外です。 XDMException は、XDMS との通信中に発生したエラー (接続の問題、XCAP ルートのパスの間違いなど) を通知します。
DocumentConflictException は、XDMException のサブクラスです。この例外は解決できない競合が検出されたことを通知します。 この例外は、XDMS 上の同一ドキュメントに複数のクライアントがアクセスしたときに発生します。 BuddyListManager は、このような競合の解決を試行した結果、解決できなかった場合にこの例外をスローします。
