9 Parlay X Web Services Multimedia Messaging API

この章では、アプリケーション開発用の Parlay X 2.1 Multimedia Messaging Web Services インタフェースのサポートについて説明します。 Web サービスは、Web サービスのユーザに代わって通知を送信、受信、およびリスンできるメッセージングエージェントとして機能します。この章の内容は以下のとおりです。

節 9.1「概要」
節 9.2「Web サービスのインストール」
節 9.3「Web サービスのコンフィグレーション」
節 9.4「メッセージング Web サービスインタフェースの説明」
節 9.5「メッセージング Web サービスインタフェースの使用」

9.1 概要

ここでは、Parlay X Gateway でサポートされる各操作のセマンティクスと実装固有の詳細について説明します。

この製品は、Parlay X 2.1 Multimedia Messaging Web Services 仕様に定義されたインタフェースをサポートしています。

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

Web サービスは標準の .ear ファイルとしてパッケージ化されており、他の Web サービスと同様に管理コンソールでデプロイできます。 .ear ファイルには、3 つのインタフェースを実装する 3 つの .war ファイルが含まれています。 Web サービスは Oracle SDP プラットフォーム、クライアント、およびプレゼンス共通の共有ライブラリを使用します。

9.3 Web サービスのコンフィグレーション

メッセージング Web サービスにコンフィグレーション可能な以下の 4 つの Mbean 属性があります。

SIPOutboundProxy : SIP メッセージの発信プロキシの SipURI。空文字列の場合、発信プロキシは存在しません。現在は IP アドレスのみをサポートしています (例 : sip:127.0.0.1:5060; lr;transport=tcp)。
SessionTimeout : HTTP セッションがタイムアウトするまでの時間を秒単位で設定します。タイムアウトしたすべてのセッションのデータが破棄されます。
MessageLifetime : メッセージの保存期間が期限切れになるまでの時間を秒単位で設定します。この値を 0 に設定すると、メッセージは無期限に保存されます (期限切れになりません)。メッセージがメッセージストアに保存される期間は最大で MessageLifetime + MessageScanPeriod 秒です。設定した属性は直ちに反映されます (たとえば、値を少なくすると、有効期間よりも古いメッセージは直ちに期限切れになります)。
MessageScanPeriod : 期限切れのメッセージをスキャンして削除する期間を秒単位で設定します。 0 に設定すると、スキャンが無効になります。設定した属性は直ちに反映されます。

9.4 メッセージング Web サービスインタフェースの説明

メッセージング Web サービスは以下の 4 つのインタフェースで構成されます。

SendMessage : メッセージを送信するメソッドのインタフェースです (表 9-1)。
ReceiveMessage : メッセージコンテンツを受信するメソッドのインタフェースです (表 9-2)。
MessageNotificationManager : Web サービスから受信したメッセージの通知対象ユーザを管理するメソッドのインタフェースです (表 9-3)。

MessageNotification : このインタフェースに定義されたクライアントコールバックを使用して、通知を送信します (表 9-4)。

表 9-1 SendMessage インタフェース

操作	説明
sendMessage	指定されたユーザに SIP MESSAGE を送信します。発信メッセージ ID を返します。
getMessageDeliveryStatus	sendMessage で送信された発信メッセージの各受信者の配信ステータスを返します。

表 9-2 ReceiveMessage インタフェース

操作	説明
getMessage	着信メッセージを受信します。
getMessageURIs	実装されていません。
getReceivedMessages	特定ユーザの一連の着信メッセージを取得します。

表 9-3 MessageNotificationManager インタフェース

操作	説明
startMessageNotification	特定のエンドポイントでユーザへのメッセージの通知を開始します。ユーザがメッセージを受信したら、エンドポイントに通知します。
stopMessageNotification	特定ユーザ宛てのエンドポイントでのメッセージの通知を停止します。

表 9-4 MessageNotification インタフェース

操作	説明
notifyMessageDeliveryReceipt	クライアントコールバックを呼び出して、ユーザにメッセージの最終的な配信ステータスを通知します。
notifyMessageReception	クライアントコールバックを呼び出して、ユーザがメッセージを受信したことをクライアントに通知します。

9.5 メッセージング Web サービスインタフェースの使用

ここでは、インタフェースの各操作の使用方法を、コード例を使用して説明します。以下の要件が適用されます。

StringSipURI 型の引数は、データ型は String ですが、sip または sips 方式を使用した有効な URI でなければなりません。この要件を満たしていない場合は ServiceException がスローされます。コンテンツ間接化 API の詳細については、『Oracle Fusion Middleware WebLogic Communication Services API Reference』を参照してください。

9.5.1 インタフェース : SendMessage、操作 : sendMessage

この操作は、指定されたユーザに SIP MESSAGE を送信します。発信メッセージ ID を返します。

表 9-5 インタフェース : SendMessage、操作 : sendMessage

引数	データ型	必須	説明
addresses	List<StringSipURI>	はい	このメッセージの送り先アドレス。
senderAddress	StringSipURI	はい	メッセージの送信者アドレス。
subject	String	いいえ	メッセージの件名。要求にプレーンテキストの添付ファイルが存在しない場合、件名はメッセージコンテンツとして扱われます。
priority	MessagePriority	いいえ	この値は無視されます。
チャージング	ChargingInformation	いいえ	この値は無視されます。
receiptRequest	SimpleReference	いいえ	メッセージの最終的な配信ステータスをアプリケーションに通知するために使用するアプリケーションのエンドポイント、インタフェース名、コリレータを定義します。
戻り値	データ型		説明
messageIdentifier	String		この識別子は getMessageDeliveryStatus 操作の呼び出しで送信メッセージの配信ステータスを取得する場合に使用します。

9.5.1.1 コード例

Map<String, Object> params = new HashMap<String, Object>();
params.put(BindingProvider.ENDPOINT_ADDRESS_PROPERTY,
    "http://webservicehost:7001/sendMessageEndpoint");
SendMessageClient sendMsgClient = new SendMessageClient(params);
List<String> recipients = new ArrayList<String>();
recipients.add("sip:receiver@example.com");
String correlator = UUID.randomUUID().toString();
SimpleReference ref = new SimpleReference();
ref.setCorrelator(correlator);
ref.setEndpoint("http://clienthost:8080/notificationEndpoint");
ref.setInterface("MessageNotification");
String msgID = sendMsgClient.sendMessage(recipients,
    "sip:sender@example.com", "message content",
    MessagePriority.DEFAULT, null, ref);

9.5.2 インタフェース : SendMessage、操作 : getMessageDeliveryStatus

この操作は、sendMessage を使用して送信した発信メッセージに対する各受信者の一連の配信ステータスを取得します。この操作の呼び出しには、sendMessage で取得した ID を指定します。

表 9-6 インタフェース : SendMessage、操作 : getMessageDeliveryStatus

引数	データ型	必須	説明
messageIdentifier	String	はい	配信ステータス要求に関連する識別子。
戻り値	データ型		説明
status	List<DeliveryInformation>		以前に送信したメッセージのステータスの一覧。送信メッセージ、送り先アドレス、配信ステータスの各項目があります。

9.5.2.1 コード例

String msgID = sendMsgClient.sendMessage(...);
List<DeliveryInformation> infoList =
    sendMsgClient.getMessageDeliveryStatus(msgID);
for (DeliveryInformation info : infoList) {
    System.out.println(“recipient: “ + info.getAddress());
    System.out.println(“status: “ + info.getDeliveryStatus());
}

9.5.3 インタフェース : MessageNotificationManager、操作 : startMessageNotification

この操作は、特定のエンドポイントでユーザへのメッセージの通知を開始します。対象ユーザのメッセージを受信すると、特定の MessageNotification エンドポイントでクライアントコールバック notifyMessageReception が呼び出されます。 Web サービスはこのユーザの受信メッセージを保存します。受信メッセージを取得する場合は ReceiveMessage インタフェースを使用します。

表 9-7 インタフェース : MessageNotificationManager、操作 : startMessageNotification

引数	データ型	必須	説明
reference	SimpleReference	はい	メッセージの受信をアプリケーションに通知するために使用するアプリケーションのエンドポイント、インタフェース名、コリレータを定義します。
messageServiceActivationNumber	StringSipURI	はい	SIP アドレス宛てのメッセージを受信したことをアプリケーションに通知します。
criteria	String	いいえ	この値は無視されます。

9.5.3.1 コード例

Map<String, Object> params = new HashMap<String, Object>();
params.put(BindingProvider.ENDPOINT_ADDRESS_PROPERTY,
    "http://webservicehost:7001/msgNotiMgrEndpoint");
MessageNotificationManagerClient msgNotiMgrClient =
    new MessageNotificationManagerClient(params);
SimpleReference ref = new SimpleReference();
String correlator = UUID.randomUUID().toString()
ref.setCorrelator(correlator);
ref.setEndpoint("http://clienthost:8080/notificationEndpoint");
ref.setInterface("MessageNotification");
msgNotiMgrClient.startMessageNotification(ref,
    "sip:receiver@example.com","dummy_criteria_ignored");

9.5.4 インタフェース : MessageNotificationManager、操作 : stopMessageNotification

この操作は、特定ユーザ宛てのエンドポイントでのメッセージの通知を停止します。対象ユーザの通知エンドポイントが存在しなくなった場合、以後、そのユーザの受信メッセージは保存されません。

表 9-8 インタフェース : MessageNotificationManager、操作 : stopMessageNotification

引数	データ型	必須	説明
correlator	String	はい	startMessageNotification operation 操作の呼び出しに関連付けられたコリレータ。

9.5.4.1 コード例

msgNotiMgrClient.stopMessageNotification(correlator);

9.5.5 インタフェース : ReceiveMessage、操作 : getReceivedMessages

この操作は、特定ユーザ宛ての一連の着信メッセージを取得します。メッセージを受信するには、MessageNotificationManager インタフェースの startMessageNotifcation 操作を呼び出して通知を有効にする必要があります。

表 9-9 インタフェース : ReceiveMessage、操作 : getReceivedMessages

引数	データ型	必須	説明
registrationIdentifier	StringSipURI	はい	着信メッセージの受信者の SIP アドレス。
priority	MessagePriority	いいえ	この値は無視されます。
戻り値	データ型		説明
references	List<MessageReference>		対象ユーザ宛ての受信メッセージの一覧。取得される項目は、メッセージ ID のみ、またはメッセージ ID とメッセージコンテンツです。

9.5.5.1 コード例

Map<String, Object> params = new HashMap<String, Object>();
params.put(BindingProvider.ENDPOINT_ADDRESS_PROPERTY,
    "http://webservicehost:7001/receiveMessageEndpoint");
ReceiveMessageClient recvMsgClient = new ReceiveMessageClient(params);
List<MessageReference> msgs =
    recvMsgClient.getReceivedMessages("sip:receiver@example.com",
    MessagePriority.DEFAULT);
for (MessageReference ref : msgs) {
    System.out.println("to: "+ref.getMessageServiceActivationNumber();
    System.out.println("from: "+ref.getSenderAddress());
    System.out.println("subject: "+ref.getSubject());
    String id = ref.getMessageIdentifier();
    if (id == null || id.isEmpty()) {
        System.out.println("message: "+ref.getMessage());
    } else {
        System.out.println("ID: "+id);
    }
}

9.5.6 インタフェース : ReceiveMessage、操作 : getMessage

この操作は、着信メッセージを添付ファイルとして受け取ります。メッセージを受信するには、MessageNotificationManager インタフェースの startMessageNotifcation 操作を呼び出して通知を有効にする必要があります。

表 9-10 Oracle WebLogic Communication Services : インタフェース : ReceiveMessage、操作 : getMessage

引数	データ型	必須	説明
messageIdentifier	String	はい	着信メッセージを識別する文字列。この文字列は notifyMessageReception コールバックまたは getReceivedMessages 操作の呼び出しによって取得します。
戻り値	データ型		説明
なし	なし		getMessage 操作を呼び出すと、メッセージコンテンツが DataHandler 型の添付ファイルに保存されます。

9.5.6.1 コード例

List<MessageReference> msgs =
    recvMsgClient.getReceivedMessages("sip:receiver@example.com",
    MessagePriority.DEFAULT);
for (MessageReference ref : msgs) {
    String id = ref.getMessageIdentifier();
    String msgContent;
    if (id == null || id.isEmpty()) {
        msgContent = ref.getMessage();
    } else {
        System.out.println("ID: " + id);
        recvMsgClient.getMessage(id);
        DataHandler dh = recvMsgClient.getAttachment();
        ByteArrayOutputStream baos = new ByteArrayOutputStream();
        BufferedOutputStream out = new BufferedOutputStream(baos);
        dh.writeTo(out);
        out.flush();
        msgContent = baos.toString();
    }
    System.out.println("message: " + msgContent);
}