この章では、Oracle User Messaging Service で使用可能な Parlay X Multimedia Messaging Web Service について、および Parlay X Web Services Multimedia Messaging API を使用して Oracle User Messaging Service でメッセージを送受信する方法について説明します。
注意 : Oracle User Messaging Service のアーキテクチャとコンポーネントの詳細については、『Oracle Fusion Middleware Getting Started with Oracle SOA Suite』を参照してください。 |
この章の内容は以下のとおりです。
注意 : Oracle User Messaging Service は Parlay X API を実装する Java クライアント ライブラリにも付属しています。 |
ここでは、Parlay X Gateway でサポートされる各操作のセマンティクスと実装固有の詳細について説明します。次の表に示す各操作の入出力メッセージ パラメータは、直接 Parlay X 仕様から取得します。
Oracle User Messaging Service は Parlay X 2.1 Multimedia Messaging 仕様のサブセットです。SendMessage インタフェースと ReceiveMessage インタフェース をサポートします。 MessageNotification インタフェースと MessageNotificationManager インタフェースはサポートしていません。
SendMessage インタフェースの sendMessage
操作を使用して、1 つまたは複数の受信者アドレスにメッセージを送信できます。以前に送信したメッセージの配信ステータスを取得するには getMessageDeliveryStatus 操作を使用します。 以下の要件が適用されます。
受信者アドレスは有効な URI であることはもちろんのこと、Oracle User Messaging Service のアドレス形式に準拠している必要があります。 一般的な形式は <配信タイプ>:<プロトコル固有アドレス> です (例 : email:user@domain、sms:5551212、im:user@jabberdomain)。
URI に使用できない文字があります。使用できない文字をアドレスに含める場合は、エンコードまたはエスケープする必要があります。 URI を適切にエンコードする方法については、『Oracle Fusion Middleware User Messaging Service API Reference』の java.net.URI に関する説明を参照してください。
WSDL では送信者アドレスに任意の文字列を指定できますが、Oracle User Messaging Service では送信者アドレスは有効なメッセージング アドレスでなければなりません。
Oracle User Messaging Service では、送信者アドレスを配信タイプごとに指定する必要があります。 したがって、たとえば配信タイプが EMAIL の受信者に送信者アドレスを適用するには、送信者アドレスの配信タイプも EMAIL にする必要があります。 この操作では複数の受信者アドレスを指定できますが、指定できる送信者アドレスは 1 つのみです。送信者アドレスは同一配信タイプの受信者のみに適用されます。
Oracle User Messaging Service は MessageNotification インタフェースをサポートしていないため、receiptRequest を指定しても配信確認は生成されません。 receiptRequest パラメータは無視されます。
表 18-1 に、sendMessage
操作の sendMessageRequest
入力についての説明を示します。
表 18-1 sendMessage 入力メッセージの説明
パート名 | パートのデータ型 | 省略 | 説明 |
---|---|---|---|
addresses |
xsd:anyURI[0..無限] |
不可 |
このメッセージの送り先アドレス。 |
senderAddress |
xsd:string |
可 |
メッセージの送信者アドレス。 このパラメータを使用できるサード パーティ プロバイダは限られています。 Parlay X サーバはアプリケーションの SLA に従ってこのパラメータを処理する必要があるため、このパラメータを使用すると PolicyException が発生します。 |
subject |
xsd:string |
可 |
メッセージの件名。 このパラメータを SMS にマップすると、senderAddress を別途指定している場合でも、このパラメータが senderAddress として扱われます。 |
priority |
MessagePriority |
可 |
メッセージの優先度。 未指定の場合、オペレータのポリシーに基づいてネットワークが優先度を割り当てます。このメッセージにはチャージングが適用されます。 |
charging |
common: ChargingInformation |
可 |
このメッセージに適用するチャージング |
receiptRequest |
common:SimpleReference |
可 |
メッセージが端末に配信されたとき、または配信が不能なときにアプリケーションに通知するために使用するアプリケーションのエンドポイント、インタフェース名、コリレータを定義します。 |
表 18-2 に、sendMessage
操作の sendMessageResponse
出力メッセージの説明を示します。
getMessageDeliveryStatus
操作は、以前に送信したメッセージの配信ステータスを取得します。 入力 requestIdentifier は sendMessage 操作の result の値です。 他のメッセージング ドキュメントでは、この識別子をメッセージ ID と呼んでいる場合があります。
表 18-3 に、getMessageDeliveryStatus
操作の getMessageDeliveryStatusRequest
入力メッセージの説明を示します。
表 18-3 getMessageDeliveryStatusRequest 入力メッセージの説明
パート名 | パートのデータ型 | 省略 | 説明 |
---|---|---|---|
registrationIdentifier |
xsd:string |
不可 |
配信ステータス要求に関連する識別子。 |
表 18-4 に、getMessageDeliveryStatus
操作の getMessageDeliveryStatusResponse 出力メッセージの説明を示します。
ReceiveMessage インタフェースには 3 つの操作があります。 getReceivedMessages
操作はサーバにポーリングして、getReceivedMessages
の最後の呼び出し以降に受信したメッセージを取得します。 getReceivedMessages
はメッセージのコンテンツを返すとは限りません。通常はメッセージのメタデータのみを返します。
他の 2 つの操作、getMessage
および getMessageURIs
はメッセージ コンテンツの取得に使用します。
この操作では、サーバにポーリングして受信メッセージを取得します。 以下の要件が適用されます。
登録 ID パラメータ (registrationIdentifier) は、アプリケーションがメッセージを受信するエンドポイント アドレスを識別する文字列です。 詳細については、ReceiveMessageManager インタフェースの説明を参照してください。
Parlay X 仕様の規定では、登録 ID が未指定の場合、対象アプリケーションのすべてのメッセージが返されますが、WSDL では登録 ID パラメータは必須です。 そこで、実装時には空の文字列 ("") を未指定の場合の値として扱います。 登録 ID に空の文字列を指定して getReceivedMessages を呼び出すと、対象アプリケーションのすべてのメッセージが返されます。 したがって、startReceiveMessages の呼び出しで登録 ID に空の文字列を指定することはできません。
Parlay X 仕様では、受信したメッセージのコンテンツが「純粋な ASCII 文字列」である場合、メッセージ コンテンツは MessageReference オブジェクト内にインラインで返され、messageIdentifier (メッセージ ID) 要素は null になります。 操作の便宜上、実装時には Content-Type が「text/plain」で Encoding が「us-ascii」のコンテンツを純粋な ASCII 文字列として扱います。 MIME 仕様では、エンコーディングが未指定の場合は「us-ascii」として扱われ、Content-Type が未指定の場合は「text/plain」として扱われます。
現在、優先度パラメータ (priority) は無視されます。
表 18-5 に、getReceivedMessages
操作の getReceivedMessagesRequest
入力メッセージの説明を示します。
表 18-5 getReceivedMessagesRequest 入力メッセージの説明
パート名 | パートのデータ型 | 省略 | 説明 |
---|---|---|---|
registrationIdentifier |
xsd:string |
不可 |
指定した条件に従ってアプリケーションがメッセージの受信通知を受け取ることができるオフライン プロビジョニング ステップを識別します。 |
priority |
MessagePriority |
可 |
Parlay X ゲートウェイからポーリングするメッセージの優先度。 指定された優先度以上のすべてのメッセージが返されます。 未指定の場合、すべてのメッセージが返されます。結果は Low を指定した場合と同じです。 |
表 18-6 に、getReceivedMessages
操作の getReceivedMessagesResponse
出力メッセージの説明を示します。
表 18-6 getReceivedMessagesResponse 出力メッセージの説明
パート名 | パートのデータ型 | 省略 | 説明 |
---|---|---|---|
registrationIdentifier |
xsd:string |
不可 |
指定した条件に従ってアプリケーションがメッセージの受信通知を受け取ることができるオフライン プロビジョニング ステップを識別します。 |
priority |
MessagePriority |
可 |
Parlay X ゲートウェイからポーリングするメッセージの優先度。 指定された優先度以上のすべてのメッセージが返されます。 未指定の場合、すべてのメッセージが返されます。 結果は Low を指定した場合と同じです。 |
getMessage
操作は、以前に getReceivedMessages を呼び出して取得したメッセージ ID を使用してメッセージ コンテンツを取得します。 応答メッセージに SOAP 本文は存在しません。コンテンツは単一の SOAP 添付ファイルとして返されます。
表 18-7 に、getMessage
操作の getMessageRequest
入力メッセージの説明を示します。
表 18-7 getMessageRequest 入力メッセージの説明
パート名 | パートのデータ型 | 省略 | 説明 |
---|---|---|---|
messageRefIdentifier |
xsd:string |
不可 |
メッセージの ID。 |
getMessage
操作に getMessageResponse
出力メッセージはありません。
getMessageURIs
は、メッセージ コンテンツを URI の一覧として取得します。 以下の要件が適用されます。
返される URI は、コンテンツを取得するために間接参照することが可能な HTTP URL です。
着信メッセージの Content-Type が「multipart」の場合、複数の URI (サブパートごとに 1 つの URI) が返されます。 Content-Type が「multipart」以外の場合、1 つの URI が返されます。
Parlay X 仕様では、「ASCII 文字列形式でエンコードされている場合はメッセージ本文」という定義に従って、受信したメッセージに本文テキスト パートが存在する場合、URI は MessageURI オブジェクト内にインラインで返されます。 実装の便宜上、この動作を以下のように定義します。
メッセージの Content-Type が「text/*」(すべてのテキスト型) で charset パラメータが「us-ascii」の場合、コンテンツは MessageURI オブジェクト内にインラインで返されます。 インラインで返されるコンテンツ以外にコンテンツは存在しないため、URI は返されません。
メッセージの Content-Type が「multipart/」(すべてのマルチパート型) で、最初の本文の Content-Type が「text/」、charset パラメータが「us-ascii」の場合、パートは MessageURI オブジェクト内にインラインで返され、そのパートに対応する URI は返されません。
MIME 仕様では、charset パラメータを省略した場合、デフォルト値の「us-ascii」として扱われます。メッセージの Content-Type ヘッダが未指定の場合、Content-Type は「text/plain」として扱われます。
表 18-8 に、getMessageURIs
操作の getMessageURIsRequest
入力メッセージの説明を示します。
表 18-8 getMessageURIsRequest 入力メッセージの説明
パート名 | パートのデータ型 | 省略 | 説明 |
---|---|---|---|
messageRefIdentifier |
xsd:string |
不可 |
取得するメッセージの ID。 |
表 18-9 に、getMessageURIs
操作の getMessageURIsResponse
出力メッセージの説明を示します。
Parlay X Messaging 仕様のメッセージング フローの一部のパートは未定義のままになっています。 未定義のままになっている主な領域は、ReceiveMessage インタフェースを使用してクライアントを同期受信用のアドレスにバインドするプロセスです。
Oracle User Messaging Service には、このプロセスをサポートするための Parlay X の拡張インタフェースが含まれています。 この拡張インタフェースは、Parlay X の正式なパートではないことを明確にするために Oracle XML 名前空間内に個別の WSDL として実装されています。クライアントはこの追加インタフェースを使用しなくてもかまいません。または、コア メッセージングのロジックを Parlay X 仕様に完全に準拠させるためにモジュール化して使用することもできます。
ReceiveMessageManager は、メッセージを受信するためのクライアントの登録を管理する Oracle 固有のインタフェースです。 クライアントはこのインタフェースを使用して特定アドレスのメッセージの受信を開始および停止します。 (この概念は Messaging API にアクセス ポイントを登録および登録解除する場合と似ています)。
この操作を呼び出して、メッセージを受信するためにクライアントを特定のエンドポイントにバインドすることができます。 以下の要件が適用されます。
エンドポイントは、Parlay X 仕様でメッセージの件名またはコンテンツの最初のスペース区切りのトークンとして定義されるアドレスとオプションの条件で構成されます。
この操作を呼び出す場合、クライアントはエンドポイント情報の他に「登録 ID」も指定します。登録 ID は、後から stopReceiveMessage
操作および getReceivedMessages
操作の特定のバインドを参照するために使用可能な一意の文字列です。
エンドポイントが別のクライアント アプリケーションによって登録済みの場合、または登録 ID がすでに使用されている場合、ポリシー エラーが発生します。
URI に使用できない文字があります。使用できない文字をアドレスに含める場合は、エンコードまたはエスケープする必要があります。 URI を適切にエンコードする方法については、『Oracle Fusion Middleware User Messaging Service API Reference』の java.net.URI に関する説明を参照してください。たとえば、XMPP メッセージを受信するために登録する場合、「IM:jabber|user@example.com」のようなアドレスを指定する必要があります。ただし、パイプ文字 (|) を URI に使用することはできないため、サーバに送信する前にエスケープする必要があります。
サーバが特定のエンドポイント アドレスのメッセージを受信できるという保証はありません。 メッセージを受信できるかどうかは、Oracle User Messaging Service の全体的なコンフィグレーション、特にシステムにデプロイされているメッセージング ドライバによって決まります。 サーバがメッセージを受信できないアドレスにクライアントがバインドされている場合、エラーは通知されません。
startReceiveMessage
操作には以下の入力および出力があります。
表 18-10 に、startReceiveMessage
の startReceiveMessageRequest
入力メッセージの説明を示します。
表 18-10 startReceiveMessageRequest 入力メッセージの説明
パート名 | パートのデータ型 | 省略 | 説明 |
---|---|---|---|
registrationIdentifier |
xsd:string |
不可 |
登録 ID |
messageService ActivationNumber |
xsd:anyURI |
不可 |
メッセージ サービスのアクティブ化番号 |
criteria |
xsd:string |
可 |
説明文字列 |
startReceiveMessage
に startReceiveMessageResponse
出力メッセージはありません。
この操作を呼び出して、以前に設定したクライアントと受信エンドポイントとの間のバインドを削除することができます。 クライアントは破棄中のエンドポイントのバインドを識別するために startReceiveMessage
を呼び出したときと同じ登録 ID を指定します。 対象アプリケーションに対してサーバが認識できる登録 ID のバインドが存在しない場合、ポリシー エラーが発生します。
表 18-11 に、stopReceiveMessage
の stopReceiveMessageRequest
入力メッセージの説明を示します。
表 18-11 stopReceiveMessageRequest 入力メッセージの説明
パート名 | パートのデータ型 | 省略 | 説明 |
---|---|---|---|
registrationIdentifier |
xsd:string |
不可 |
登録 ID |
stopReceiveMessage
に stopReceiveMessageResponse
出力メッセージはありません。
Parlay X WSDL ファイルと Web サービス アセンブリ ツールのみを使用して Parlay X Messaging Client をアセンブルすることも可能ですが、サポートされる Parlay X Messaging インタフェースに対応したビルド済みの Web サービス スタブおよびインタフェースも用意されています。 SOAP 添付ファイルを含む Web サービスを Parlay X で規定されたスタイルでアセンブルする手順は複雑なので、WSDL からアセンブルするのではなく、付属の API を使用することをお勧めします。
Parlay X Messaging API で使用可能なクラスの詳細な一覧については、『Oracle Fusion Middleware User Messaging Service API Reference』を参照してください。 API の主なエントリ ポイントには以下のクライアント クラスがあります。
oracle.sdp.parlayx.multimedia_messaging.send.SendMessageClient
oracle.sdp.parlayx.multimedia_messaging.receive.ReceiveMessageClient
oracle.sdp.parlayx.multimedia_messaging.extension.receive_manager. ReceiveMessageManager
上記の各クライアント クラスを使用して、クライアント アプリケーションから対応するインタフェースで操作を呼び出すことができます。 クライアント クラスのインスタンスを作成すると、リモート ゲートウェイ URL や必要なセキュリティ資格情報などの追加 Web サービス パラメータを指定できるようになります。 詳細については、『Oracle Fusion Middleware User Messaging Service API Reference』 を参照してください。 Parlay X 仕様の規定に従って、セキュリティ資格は標準の WS-Security ヘッダーを使用してサーバに伝播されます。
クライアント アプリケーションの一般的なプロセスでは、前述のクライアント クラスのいずれかを作成し、必要なコンフィグレーション項目 (エンドポイント、ユーザ名、パスワード) を設定し、いずれかのビジネス メソッド (SendMessageClient.sendMessage() など) を呼び出します。 この API の使用例については、Oracle Technology Network (OTN) のメッセージング サンプル (usermessagingsample-parlayx-src.zip) を参照してください。
この章では、OTN のOracle User Messaging Service に付属している Parlay X API を使用したサンプル チャット アプリケーションの作成、デプロイ、実行方法について説明します。
注意 : Oracle User Messaging Service のアーキテクチャとコンポーネントの詳細については、『Oracle Fusion Middleware Getting Started with Oracle SOA Suite』を参照してください。 |
この章の内容は以下のとおりです。
このサンプルでは、Web ベースのチャット アプリケーションを作成して電子メール、SMS、または IM のメッセージを送受信する方法について説明します。 サンプルでは、User Messaging サーバとの通信に標準ベースの Parlay X Web サービス API を使用しています。サンプル アプリケーションの 3 つの Web サービス インタフェース (Parlay X によって定義された SendMessage サービスと ReceiveMessage サービス、および Oracle の Parlay X 用拡張機能である ReceiveMessageManager サービス) には、それぞれ Web サービス プロキシ コードが含まれています。JDeveloperにアプリケーション サーバの接続を定義し、このアプリケーションをデプロイして実行する必要があります。このアプリケーションは単純な Web チャット インタフェースを含むビルド済みの Oracle JDeveloper プロジェクトとして提供されています。
以下の手順に従って、ビルド前のサンプルを実行し、デプロイします。
Oracle JDeveloper の zip ファイルに含まれている usermessagingsample-parlayx.jws を開きます。
Oracle JDeveloper メイン ウィンドウにプロジェクトが表示されます。
Oracle JDeveloper で、[ファイル|開く] を選択し、上記のディレクトリに移動して、ワークスペース ファイル usermessagingsample-parlayx.jws を開きます。
Parlay X サンプル アプリケーション用に作成済みの JDeveloper アプリケーションが開きます。 このアプリケーションでは 1 つの Web モジュールを使用しています。 アプリケーションのすべてのソース コードが含まれています。 インストール固有のパラメータをコンフィグレーションする必要があります。
Web モジュールにライブラリを追加して、サンプル アプリケーションのビルドの依存関係を満たします。
アプリケーション ナビゲータで、Web モジュール usermessagingsample-parlayx-war を右クリックし、[Project Properties] を選択します。
左のペインで、[Libraries and Classpath] を選択します。
[Add Library] をクリックします。
新しいライブラリを定義するため [新規] をクリックします。
[ライブラリ名] に「oracle.sdp.client」と入力します。
[クラスパス] を選択した状態で [エントリの追加] を選択します。
<JDeveloper のベース ディレクトリ>/communications/modules/oracle.sdp.client_11.1.1 に移動して jar ファイル「sdpclient.jar」を選択します。
すべてのポップアップで [OK ]または [Accept] をクリックしてライブラリを作成し、ライブラリをサンプル Web モジュールへの依存関係として追加します。
ナビゲーション ペインでプロジェクトを右クリックし、[新規] を選択してアプリケーション サーバ接続を作成します。 節 18.6.4「新しいアプリケーション サーバ接続の作成」の手順に従います。
プロジェクトをデプロイするには、[usermessasgingsample-parlayx project|Deploy|usermessasgingsample-parlayx|to|SOA_server] を選択します (図 18-6)。
ログに「Build Successful」というメッセージが表示されることを確認します。
デフォルトのリビジョンを入力し、[OK] をクリックします。
デプロイメント ログに「Deployment Finished」というメッセージが表示されることを確認します。
これで、アプリケーションのデプロイは完了です。
サンプルを実行するには、次の節で説明するように、Oracle User Messaging Service の追加ドライバをコンフィグレーションし、User Messaging Preferences でメッセージを受信するユーザのデフォルト デバイスもコンフィグレーションする必要があります。
注意 : 詳細については、『Oracle Fusion Middleware SOA Developer's Guide』の「Configuring Notifications」を参照してください。 |
以下の手順に従って、サンプルを実行し、テストします。
Web ブラウザを開きます。
次のようにアプリケーションの URL に移動し、ログインします。
http://<ホスト>:<ポート>/usermessagingsample-parlayx/
Messaging Parlay X サンプルの Web ページが表示されます (図 18-7)。 このページには、ナビゲーション タブとアプリケーションの手順が表示されます。
[Configure] をクリックし、以下の値を入力します (図 18-8)。
[Send endpoint] を指定します (例 : http://localhost:port/sdpmessaging/parlayx/SendMessageService)
[Receive endpoint] を指定します (例 : http://localhost:port/sdpmessaging/parlayx/ReceiveMessageService)
[Receive Manager endpoint] を指定します (例 : http://localhost:port/sdpmessaging/parlayx/ReceiveMessageMessageService)
[Username] と [Password] を指定します。
[Policy] を指定します (User Messaging Service インスタンスの WS セキュリティが有効になっている場合には必須)。
[保存] をクリックします。
[Manage] をクリックします。
登録 ID を入力し、登録とメッセージの受信アドレスを指定します (図 18-9)。 このページで、特定アドレスのメッセージの受信を停止することもできます。
[Start] をクリックします。
「Registration operation succeeded」というメッセージが表示されること確認します。
[Chat] をクリックします (図 18-10)。
[To:] フィールドに 図 18-10 の形式で受信者を入力します。
メッセージを入力します。
[Send] をクリックします。
メッセージが受信されていることを確認します。
新しいアプリケーション サーバ接続を作成するには、以下の手順に従います。
新しいアプリケーション サーバ接続を作成するには、プロジェクトを右クリックし、[新規|接続|Application Server Connection] を選択します (図 18-11)。
接続名に「SOA_server」を指定して [次へ] をクリックします (図 18-12)。
[接続タイプ] に「WebLogic 10.3」を指定します。
認証情報を入力します。一般的な値は次のとおりです。
ユーザ名 : weblogic
、パスワード : weblogic
[接続] 画面で、ホスト名、ポート、SOA 管理サーバの SSL ポート、WLS ドメインのドメイン名を入力します。
[次へ] をクリックします。
[テスト] 画面で、[接続のテスト] をクリックします。
「Success!」というメッセージが表示されることを確認します。
アプリケーション サーバ接続の作成は完了しました。