この章では、ユーザー・メッセージング・サービス(UMS)WebサービスAPIを使用してアプリケーションを開発する方法について説明します。このAPIは、Fusion Middlewareアプリケーション開発者が、UMSサーバーに関連するリモート・コンテナで実行されるUMSメッセージング・アプリケーションを実装する際の、プログラム上のエントリ・ポイントとして機能します。
項目は次のとおりです。
注意: Oracle User Messaging Serviceのコード・サンプルに関する詳細を参照したり、サンプルを自分で実行するには、URL:https://soasamples.samplecode.oracle.com/ にあるOracle Technology Networkのコード・サンプル・ページを参照してください。
このページにナビゲートした後は、検索条件の「UMS」を入力して「検索」をクリックすることで、Oracle User Messaging Serviceのコード・サンプルを検出できます。 |
UMS WebサービスAPIは、機能的にはJava APIと同じです。Webサービス・タイプおよびインタフェースのJAX-WSおよびJAXBバインディングは、対応するJava APIクラスと同じように命名されているものの、別個のパッケージ空間にあります。この2つのAPIのクラスには相互運用性はありません。
このAPIのコンシューマは、ファクトリ・メソッドを使用してMessagingClient
オブジェクトのインスタンスを取得できます。デプロイメントは、共有ライブラリ「oracle.sdp.client」としてです。
UMS WebサービスAPIは、次のようにグループ化されたパッケージで構成されています。
共通およびクライアントのパッケージ
oracle.ucs.messaging.ws
oracle.ucs.messaging.ws.types
WebサービスAPIのWeb Service Definition Language(WSDL)ファイル
messaging.wsdl: Webサービス・クライアントによって起動される操作を定義します。
listener.wsdl: 非同期メッセージまたはステータス通知を受信するためにクライアントで実装する必要のあるコールバック操作を定義します。
ソース・コードを含むサンプルは、Oracle Technology Network(OTN)から入手できます。
この項では、UMSクライアントを作成するための要件を示します。oracle.ucs.messaging.ws.MessagingClient
のインスタンスはパブリック・コンストラクタを使用して作成できます。クライアント・アプリケーションでは、クライアント・オブジェクトのインスタンス化の実行時に一連のパラメータを指定できます。たとえば、MessagingClient
インスタンスを構成するには、複数のパラメータをキーと値のペアのマップとしてjava.util.Map<String, Object>
に指定します。特に、これらの構成パラメータは、通信先のUMSサーバーを識別することによるWebサービスのエンドポイントURLの識別、およびセキュリティ・ポリシーなどの他のWebサービス関連情報の識別に役立ちます。クライアント・アプリケーションでは、使用可能なメカニズムを使用して構成パラメータを保存およびロードする必要があります。
デプロイメントに適した構成ストレージ・メカニズムがどのようなものであっても、それへのパラメータのマッピング、またはそこからのパラメータのマッピングは、ユーザーの責任です。MessagingClient
クラスでは指定されたキーと値のペアが構成のために使用され、ベースとなるJAX-WSサービスにすべてのパラメータが渡されます。JAX-WSで認識されるパラメータはいずれも有効です。表62-1に、最も一般的な構成パラメータを示します。
表62-1 実行時に指定する構成パラメータ
キー | 用途 |
---|---|
|
リモートUMS WSのエンドポイントURL。これは通常「http://<host>:<port>/ucs/messaging/webservice」です。 |
|
該当する場合にWS-Securityヘッダーにアサートされるユーザー名。 |
|
クライアントの要求に添付する一連のOWSM WS-Securityポリシー。サーバー側で指定されたポリシーと一致する必要があります。 |
oracle.wsm.security.util.SecurityConstants.Config.KEYSTORE_RECIPIENT_ALIAS_PROPERTY |
OWSMポリシーのアタッチに使用されます。資格証明ストアからの暗号化キーおよび署名キーの参照に使用する代替エイリアスを指定します。 |
oracle.wsm.security.util.SecurityConstants.ClientConstants.WSS_CSF_KEY |
OWSMポリシーのアタッチに使用されます。Oracle Web Services Management資格証明ストア・マップからのリモート・ユーザー名/パスワード情報の参照に使用する資格証明ストア・キーを指定します。 |
インスタンス化された後のMessagingClient
は、再構成できません。かわりに、新しい構成を使用してMessagingClient
クラスの新しいインスタンスを作成する必要があります。
例62-1に、ユーザー名/トークンによるセキュリティを使用して、プログラミングによってMessagingClient
インスタンスを作成する場合のコードを示します。
例62-1 プログラミングによるMessagingClientインスタンスの作成(ユーザー名/トークンによるセキュリティ)
HashMap<String, Object> config = new HashMap<String, Object>(); config.put(BindingProvider.ENDPOINT_ADDRESS_PROPERTY, "http://example.com:8001/ucs/messaging/webservice"); config.put(ClientConstants.POLICIES, new String[] {"oracle/wss11_username_token_ with_message_protection_client_policy"}); config.put(BindingProvider.USERNAME_PROPERTY, "user1"); config.put(oracle.wsm.security.util.SecurityConstants.Config.CLIENT_CREDS_ LOCATION, oracle.wsm.security.util.SecurityConstants.Config.CLIENT_CREDS_LOC_ SUBJECT); config.put(oracle.wsm.security.util.SecurityConstants.ClientConstants.WSS_CSF_KEY, "user1-passkey"); config.put(MessagingConstants.APPLICATION_NAME, "MyUMSWSApp"); mClient = new MessagingClient(config);
例62-2に、SAMLトークンによるセキュリティを使用して、プログラミングによってMessagingClient
インスタンスを作成する場合のコードを示します。
例62-2 プログラミングによるMessagingClientインスタンスの作成(SAMLトークンによるセキュリティ)
HashMap<String, Object> config = new HashMap<String, Object>(); config.put(BindingProvider.ENDPOINT_ADDRESS_PROPERTY, "http://example.com:8001/ucs/messaging/webservice"); config.put(ClientConstants.POLICIES, new String[] {"oracle/wss11_saml_token_ identity_switch_with_message_protection_client_policy"}); config.put(BindingProvider.USERNAME_PROPERTY, "user1"); config.put(oracle.wsm.security.util.SecurityConstants.Config.CLIENT_CREDS_ LOCATION, oracle.wsm.security.util.SecurityConstants.Config.CLIENT_CREDS_LOC_ SUBJECT); config.put(oracle.wsm.security.util.SecurityConstants.Config.KEYSTORE_RECIPIENT_ ALIAS_PROPERTY, "example.com"); config.put(MessagingConstants.APPLICATION_NAME, "MyUMSWSApp"); mClient = new MessagingClient(config);
インスタンス化された後のMessagingClient
は、再構成できません。かわりに、任意の構成を使用してMessagingClient
クラスの新しいインスタンスを作成する必要があります。
WebサービスAPIタイプを作成するためのファクトリ・メソッドが、クラス「oracle.ucs.messaging.ws.MessagingFactory
」に用意されています。
send
メソッドを起動すると、メッセージがUMSに配信されて適切に処理されます。send
メソッドは、メッセージの配信ステータスを取得したり、リスナーに配信される非同期ステータス通知と関連付けたりするために後でクライアント・アプリケーションで使用できる、String message
識別子を戻します。戻されたステータスは、UMSの内部処理と外部ゲートウェイから受信した配信通知に基づいた最新のステータスです。
作成できるメッセージのタイプには、プレーン・テキスト・メッセージ、text/plainパートとtext/htmlパートで構成できるマルチパート・メッセージ、および異なる配信タイプを使用して、複数受信者用の単一メッセージに配信チャネル(DeliveryType
)固有のペイロードを作成するメッセージがあります。
この項では、作成できる様々なタイプのメッセージについて説明します。
例62-3に、UMS WebサービスAPIを使用してプレーン・テキスト・メッセージを作成する方法を示します。
例62-3 UMS WebサービスAPIを使用したプレーン・テキスト・メッセージの作成
Message message = MessagingFactory.createTextMessage("This is a Plain Text message."); Message message = MessagingFactory.createMessage(); message.setContent(new DataHandler(new StringDataSource("This is a Plain Text message.", "text/plain; charset=UTF-8")));
例62-4に、UMS WebサービスAPIを使用してマルチパート/混合メッセージを作成する方法を示します。
例62-4 UMS WebサービスAPIの使用によるマルチパート/混合メッセージの作成
Message message = MessagingFactory.createMessage(); MimeMultipart mp = new MimeMultipart("mixed"); // Create the first body part MimeBodyPart mp_partPlain = new MimeBodyPart(); StringDataSource plainDS = new StringDataSource("This is a Plain Text part.", "text/plain; charset=UTF-8"); mp_partPlain.setDataHandler(new DataHandler(plainDS)); mp.addBodyPart(mp_partPlain); byte[] imageData; // Create or load image data in the above byte array (code not shown for brevity) // Create the second body part MimeBodyPart mp_partBinary = new MimeBodyPart(); ByteArrayDataSource binaryDS = new ByteArrayDataSource(imageData, "image/gif"); mp_partBinary.setDataHandler(binaryDS); mp.addBodyPart(mp_partBinary); message.setContent(new DataHandler(mp, mp.getContentType()));
例62-5に、UMS WebサービスAPIを使用してマルチパート/代替メッセージを作成する方法を示します。
例62-5 UMS WebサービスAPIの使用によるマルチパート/代替メッセージの作成
Message message = MessagingFactory.createMessage(); MimeMultipart mp = new MimeMultipart("alternative"); MimeBodyPart mp_partPlain = new MimeBodyPart(); StringDataSource plainDS = new StringDataSource("This is a Plain Text part.", "text/plain; charset=UTF-8"); mp_partPlain.setDataHandler(new DataHandler(plainDS)); mp.addBodyPart(mp_partPlain); MimeBodyPart mp_partRich = new MimeBodyPart(); StringDataSource richDS = new StringDataSource( "<html><head></head><body><b><i>This is an HTML part.</i></b></body></html>", "text/html"); mp_partRich.setDataHandler(new DataHandler(richDS)); mp.addBodyPart(mp_partRich); message.setContent(new DataHandler(mp, mp.getContentType()));
メッセージを宛先アドレスに送信する際は、複数のチャネルが関連する場合があります。Oracle UMSアプリケーション開発者は、各チャネルに対して正しいマルチパート書式を指定する必要があります。
例62-6に、異なる配信タイプを使用して、複数受信者用の単一メッセージに、配信チャネル(DeliveryType
)固有のペイロードを作成する方法を示します。
複数ペイロードのマルチパート/代替メッセージの各最上位パートには、このヘッダーの値が1つ以上含まれている必要があります。このヘッダーの値は、有効な配信タイプの名前である必要があります。DeliveryTypeの使用可能な値は、列挙DeliveryType
を参照してください。
例62-6 異なる配信タイプを使用した、複数受信者用の単一メッセージへの配信チャネル固有のペイロード作成
Message message = MessagingFactory.createMessage(); // create a top-level multipart/alternative MimeMultipart object. MimeMultipart mp = new MimeMultipart("alternative"); // create first part for SMS payload content. MimeBodyPart part1 = new MimeBodyPart(); part1.setDataHandler(new DataHandler(new StringDataSource("Text content for SMS.", "text/plain; charset=UTF-8"))); part1.setHeader(Message.HEADER_NS_PAYLOAD_PART_DELIVERY_TYPE, "SMS"); // add first part mp.addBodyPart(part1); // create second part for EMAIL and IM payload content. MimeBodyPart part2 = new MimeBodyPart(); MimeMultipart part2_mp = new MimeMultipart("alternative"); MimeBodyPart part2_mp_partPlain = new MimeBodyPart(); part2_mp_partPlain.setDataHandler(new DataHandler(new StringDataSource("Text content for EMAIL/IM.", "text/plain; charset=UTF-8"))); part2_mp.addBodyPart(part2_mp_partPlain); MimeBodyPart part2_mp_partRich = new MimeBodyPart(); part2_mp_partRich.setDataHandler(new DataHandler(new StringDataSource("<html><head></head><body><b><i>" + "HTML content for EMAIL/IM." + "</i></b></body></html>", "text/html; charset=UTF-8"))); part2_mp.addBodyPart(part2_mp_partRich); part2.setContent(part2_mp, part2_mp.getContentType()); part2.addHeader(Message.HEADER_NS_PAYLOAD_PART_DELIVERY_TYPE, "EMAIL"); part2.addHeader(Message.HEADER_NS_PAYLOAD_PART_DELIVERY_TYPE, "IM"); // add second part mp.addBodyPart(part2); // set the content of the message message.setContent(new DataHandler(mp, mp.getContentType())); // set the MultiplePayload flag to true MimeHeader multiHeader = new MimeHeader(); multiHeader.setName(oracle.sdp.messaging.Message.HEADER_SDPM_MULTIPLE_PAYLOAD); multiHeader.setValue(Boolean.TRUE.toString()); message.getHeaders().add(multiHeader);
この項では、アドレスのタイプおよびAddressオブジェクトの作成方法について説明します。
アドレスには、デバイス・アドレスとユーザー・アドレスの2種類があります。デバイス・アドレスには、電子メール・アドレス、インスタント・メッセージ・アドレス、電話番号など、様々なタイプがあります。ユーザー・アドレスは、ユーザー・リポジトリにあるユーザーIDです。
Address
インタフェースで定義するAddress
オブジェクトは、MessagingFactory
クラスを使用してメッセージの送信者と受信者のアドレスを指定することで作成できます。
WS APIでは、電子メール・ドライバで使用されるTo/Cc/Bcc受信者を使用したメッセージの送受信をサポートしています。
メッセージの送信でCc/Bcc受信者を指定するには、oracle.ucs.messaging.ws.MessagingFactory.buildAddress
メソッドを使用してoracle.ucs.messaging.ws.Address
オブジェクトを作成します。引数はアドレス値(たとえばuser@domain.com)、配信タイプ(たとえばDeliveryType.EMAIL
)および電子メール・モード(たとえば「Cc」や「Bcc」)です。
(たとえば受信したメッセージ内にある)既存のアドレス・オブジェクトの受信者タイプを特定するには、oracle.ucs.messaging.ws.MessagingFactory.getRecipientType
メソッドを使用してAddressオブジェクトを渡します。それに対して受信者タイプを示す文字列が戻されます。
ユーザー受信者にメッセージを送信(してユーザーのメッセージング・プリファレンスを活用)する際、メッセージで様々なビジネス条件のファクト(現在の値)をメタデータとして渡すことができます。UMSサーバーでは、メッセージで指定されたファクトを、ユーザーのメッセージング・フィルタで指定されているビジネス条件の条件と照合します。
注意: すべてのファクトはメタデータとしてoracle.sdp.messaging.Message.NAMESPACE_NOTIFICATION_PREFERENCES 名前空間に追加する必要があります。他の名前空間のメタデータは(ユーザー・メッセージング・プリファレンスの解決においては)無視されます。 |
図62-11は、ユーザー受信者を指定し、メッセージのユーザー・プリファレンスでビジネス条件のファクトを指定する方法を示します。サポートされているビジネス条件の完全なリストは、第64章「ユーザー・メッセージング・プリファレンス」を参照してください。
例62-11 ユーザー・プリファレンス・ベースのメッセージング
Message message = MessagingFactory.createMessage(); // create and add a user recipient Address userRecipient1 = MessagingFactory.createAddress("USER:sampleuser1"); message.addRecipient(userRecipient1); // specify business term facts MessagingFactory.setMetadata(message, oracle.sdp.messaging.Message.NAMESPACE_ NOTIFICATION_PREFERENCES, "Customer Name", "ACME"); // where "Customer Name" is the Business Term name, and "ACME" is the Business Term value (i.e, fact).
メッセージを送信した後は、Oracle UMSを使用して、メッセージ・ステータスを同期または非同期で取得できます。
現行ステータスの同期取得を実行するには、MessagingClient
APIから次のフローを使用します。
String messageId = messagingClient.send(message); List<Status> statuses = messagingClient.getStatus(messageId, null)
または、
List<Status> statuses = messagingClient.getStatus(messageId, addresses) --- where addresses is a "List<Address>" of one or more of the recipients set in the message.
ステータスを非同期的で取得するには、listener.wsdl
に記載されていListener Webサービスがクライアント・アプリケーションで実装されている必要があります。リスナー・エンドポイントの実装方法に制約はありません。たとえば、1つの方法は、javax.xml.ws.Endpoint
JAX-WS Service APIを使用してWebサービス・エンドポイントをパブリッシュすることです。このメカニズムはJava SE 6で利用でき、コンシューマはJava EEサーブレット・モジュールを明示的に定義する必要はありません。
ただし、サーブレット・ベースのリスナー実装も可能です。
メッセージを送信する際、クライアント・アプリケーションは、エンドポイントURLおよびSOAPインタフェース名で構成されるリスナー・エンドポイントへの参照を提供できます。ステータスはメッセージの処理中に生成されるため、UMSサーバーはリスナー・エンドポイントのonStatus
メソッドを呼び出してクライアント・アプリケーションに通知します。
リスナーは純粋なプログラムです。リスナーは、oracle.ucs.messaging.ws.Listener
インタフェースを実装して作成します。このインタフェースは、具体クラス(既存クラスの1つ、新規クラス、あるいは無名クラスか内部クラス)として実装できます。
次のコード例は、ステータス・リスナーの実装方法を示しています。
@PortableWebService(serviceName="ListenerService", targetNamespace="http://xmlns.oracle.com/ucs/messaging/", endpointInterface="oracle.ucs.messaging.ws.Listener", wsdlLocation="META-INF/wsdl/listener.wsdl", portName="Listener") public class MyListener implements Listener { public MyListener() { } @Override public void onMessage(Message message, byte[] correlator) throws MessagingException { System.out.println("I got a message!"); } @Override public void onStatus(Status status, byte[] correlator) throws MessagingException { System.out.println("I got a status!"); } }
コールバック・サービスをパブリッシュするには、アプリケーション内のWebモジュールのweb.xmlでサーブレットを宣言するか、またはJAX-WSのjavax.xml.ws.Endpointクラスのパブリッシュ・メソッドを使用してプログラムによりWSエンドポイントをパブリッシュします(例62-12)。
動的にパブリッシュされたエンドポイントを停止するには、Endpoint.publish()
から戻されたEndpointオブジェクトでstop()
メソッドを呼び出します(例62-13)。
リスナーWebサービスがパブリッシュされると、そのようなエンドポイントがクライアントにあることを登録する必要があります。MessagingClient APIには次の関連メソッドがあります。
setStatusListener(ListenerReference listener)
send(Message message, ListenerReference listener, byte[] correlator)
setStatusListener()
ではデフォルトのステータス・リスナーを登録し、着信ステータス・メッセージに対してはそのリスナーのコールバックが呼び出されます。send()
に渡されたリスナーは、対応するメッセージに関連するステータス更新に対してのみ呼び出されます。
この項では、アプリケーションでメッセージを受信する方法について説明します。メッセージを受信するには、最初にアクセス・ポイントを登録する必要があります。アプリケーション側から見ると、メッセージを受信するモードには同期と非同期があります。
クライアント・アプリケーションではアクセス・ポイントを作成して登録し、特定のアドレスに送信された着信メッセージを受信するように指定できます。アクセス・ポイントを登録する際、クライアント・アプリケーションでは、エンドポイントURLおよびSOAPインタフェース名で構成されるリスナー・エンドポイントへの参照を指定できます。メッセージが届くと、UMSサーバーではリスナー・エンドポイントのonMessage
メソッドを呼び出してクライアント・アプリケーションに通知します。
この場合、クライアント・アプリケーションでは、受信メソッドを起動して保留中のメッセージをフェッチできます。アクセス・ポイントの指定なしでメッセージを受信した場合、アプリケーションでは、登録したすべてのアクセス・ポイントのメッセージを受信します。アクセス・ポイントが指定されている場合、アプリケーションでは、そのアクセス・ポイントに送信されたメッセージを受信します。
AccessPoint
は、着信メッセージを受信するための1つ以上のデバイス・アドレスを表します。着信メッセージを受信するアプリケーションでは、メッセージの受信者アドレスを表すアクセス・ポイントを1つ以上登録する必要があります。サーバーでは、着信メッセージの受信者アドレスと一連の登録済アクセス・ポイントを照合し、一致したアクセス・ポイントを登録したアプリケーションに、その着信メッセージをルーティングします。
MessagingFactory.createAccessPoint
を使用してアクセス・ポイントを作成し、そのアクセス・ポイントをMessagingClient.registerAccessPoint
を使用してメッセージ受信用に登録できます。
番号9000
のSMSアクセス・ポイントを登録するには、次のように指定します。
AccessPoint accessPointSingleAddress = MessagingFactory.createAccessPoint(AccessPointType.SINGLE_ADDRESS, DeliveryType.SMS, "9000"); messagingClient.registerAccessPoint(accessPointSingleAddress);
番号が9000
から9999
の範囲内のSMSアクセス・ポイントを登録するには、次のように指定します。
AccessPoint accessPointRangeAddress = MessagingFactory.createAccessPoint(AccessPointType.NUMBER_RANGE, DeliveryType.SMS,"9000,9999"); messagingClient.registerAccessPoint(accessPointRangeAddress);
受信は非ブロック操作です。アプリケーションやアクセス・ポイントに関して保留中のメッセージがない場合、該当するコールでは、空のリストが即時に戻されます。受信によって、すべての使用可能なメッセージが戻される保証はありませんが、効率上の理由から使用可能なメッセージのサブセットのみを戻すことはできます。
メッセージの同期受信には、メソッドMessagingClient.receive
を使用できます。このメソッドは、メッセージの非同期受信による構成オーバーヘッドを望まない軽量なクライアント向けの便利なポーリング・メソッドです。このメソッドは、アプリケーションのインバウンド・キューですぐに使用できるメッセージのリストを戻します。
このメソッドは非ブロック・コールを実行するため、現在使用できるメッセージがない場合はNULLを戻します。
注意: 1回の起動で、使用可能なメッセージがすべて取得される保証はありません。ポーリングして、使用可能なすべてのメッセージを受信したことを確認する必要があります。 |
メッセージを非同期で受信するには、listener.wsdl
に記載されているListener
Webサービスがクライアント・アプリケーションで実装されている必要があります。リスナー・エンドポイントの実装方法に制約はありません。たとえば1つのメカニズムは、javax.xml.ws.Endpoint
JAX-WS Service API を使用してWebサービス・エンドポイントをパブリッシュすることです。このメカニズムはJava SE 6で利用でき、コンシューマはJava EEサーブレット・モジュールを明示的に定義する必要はありません。ただし、サーブレット・ベースのリスナー実装も可能です。
リスナーは純粋なプログラムです。リスナーは、oracle.ucs.messaging.ws.Listener
インタフェースを実装して作成します。このインタフェースは、具体クラス(既存クラスの1つ、新規クラス、あるいは無名クラスか内部クラス)として実装できます。
次のコード例は、メッセージ・リスナーの実装方法を示しています。
@PortableWebService(serviceName="ListenerService", targetNamespace="http://xmlns.oracle.com/ucs/messaging/", endpointInterface="oracle.ucs.messaging.ws.Listener", wsdlLocation="META-INF/wsdl/listener.wsdl", portName="Listener") public class MyListener implements Listener { public MyListener() { } @Override public void onMessage(Message message, byte[] correlator) throws MessagingException { System.out.println("I got a message!"); } @Override public void onStatus(Status status, byte[] correlator) throws MessagingException { System.out.println("I got a status!"); } }
リスナー・オブジェクトへの参照は、「デフォルトのメッセージ・リスナー」および「アクセス・ポイントごとのメッセージ・リスナー」の説明に従って、setMessageListener
またはregisterAccessPoint
メソッドに渡します。アプリケーションのメッセージが着信すると、UMSインフラストラクチャでは、リスナーのonMessage
メソッドが起動されます。
クライアント・アプリケーションでは通常、デフォルトのメッセージ・リスナー(例62-14)が設定されます。このリスナーは、このクライアント・アプリケーションによって送信されたメッセージの中で、関連するリスナーがないメッセージの配信ステータスに対して起動されます。Oracle UMSでは、このクライアント・アプリケーションによって登録されたアクセス・ポイント宛てのメッセージを受信すると、そのクライアント・アプリケーションのデフォルトのリスナーに対してonMessage
コールバックが起動されます。
デフォルトのリスナーを削除するには、nullの引数を指定してこのメソッドをコールします。
クライアント・アプリケーションでは、アクセス・ポイントを登録し、Listener
オブジェクトとオプションの相関機能オブジェクトを指定できます(例62-15)。受信メッセージが指定のアクセス・ポイント・アドレスに着信すると、指定したリスナーのonMessage
メソッドが起動されます。当初指定の相関機能オブジェクトもコールバック・メソッドに渡されます。
アプリケーションでMessageFilter
を使用すると、配信されるメッセージをより強力に制御できます。MessageFilter
には、一致基準とアクションが含まれています。アプリケーションでは、一連のメッセージ・フィルタを登録できます。登録されたメッセージ・フィルタは、着信(受信)メッセージに順に適用され、メッセージが基準と一致するとアクションが実行されます。たとえば、アプリケーションでMessageFilters
を使用して必要なブラックリストを実装すると、指定した送信者アドレスからのすべてのメッセージを拒否できます。
MessagingFactory.createMessageFilter
を使用してメッセージ・フィルタを作成し、そのメッセージ・フィルタをMessagingClient.registerMessageFilter
を使用して登録できます。フィルタは、アプリケーションの現行フィルタ・チェーンの最後に追加されます。受信したメッセージは、フィルタ・チェーンを順に通過します。メッセージがフィルタの基準に一致すると、そのフィルタのアクションが即時に実行されます。メッセージがフィルタに一致しない場合のデフォルト・アクションでは、そのメッセージが受信されてアプリケーションに配信されます。たとえば、件名が"spam"
のメッセージを拒否するには、次のように指定します。
MessageFilter subjectFilter = MessagingFactory.createMessageFilter("spam", FilterFieldType.SUBJECT, null, FilterActionType.REJECT); messagingClient.registerMessageFilter(subjectFilter);
電子メール・アドレスspammer@foo.com
からのメッセージを拒否するには、次のように指定します。
MessageFilter senderFilter = MessagingFactory.createBlacklistFilter("spammer@foo.com"); messagingClient.registerMessageFilter(senderFilter);
APIでは、クラスタ環境にクライアント・アプリケーションとUMSサーバーがデプロイされている環境をサポートしています。クラスタ化されたデプロイメントが期待どおりに機能するためには、クライアント・アプリケーションを正しく構成する必要があります。次のルールが適用されます。
2つのクライアント・アプリケーションで同じApplicationName
構成パラメータが使用されている場合、同じアプリケーションのインスタンスであるとみなされます。
ApplicationInstanceName
構成パラメータを使用すると、インスタンスを相互に区別できます。
アプリケーション・セッションは、インスタンス固有です。メッセージにセッション・フラグを設定すると、メッセージを送信したインスタンスが受信した返信を確認できます。
リスナー相関機能は、インスタンス固有です。1つのアプリケーションの2つの異なるインスタンスで複数のリスナーが登録され、異なる相関機能が提供されている場合は、インスタンスAのリスナーが起動されると相関機能Aが提供され、インスタンスBのリスナーが起動されると相関機能Bが提供されます。
次の項ではセキュリティに関する考慮事項が説明されています。
UMS Web サービスでは、Security Assertions Markup Language(SAML)トークンとユーザー名トークンの2つのセキュリティ・モードがサポートされています。
サポートされているSAMLベースのポリシーは「oracle/wss11_saml_token_with_message_protection_client_policy」です。このポリシーにより、暗号キーの交換に基づいて、クライアント・アプリケーションとUMSサーバーの間の信頼関係が確立されます。これにより、クライアント・アプリケーションではUMSサーバーによって受け付けられるユーザー・アイデンティティをアサートできるようになります。WS-SecurityでSAMLトークンを使用するには、クライアントとサーバーの両方でキーストアの構成がいくらか必要になります。UMS Webサービス・クライアントでのSAMLセキュリティの構成の詳細は、例62-2を参照してください。
サポートされているユーザー名トークン・ポリシーは"oracle/wss11_username_token_with_message_protection_client_policy"です。このポリシーがWS-Securityヘッダーで暗号化されたユーザー名/パスワードのトークンを渡し、指定された資格証明をサーバーが認証します。ユーザー名とパスワードは資格証明ストアに格納することをお薦めします。こうすると、MessagingClientコンストラクタには資格証明ストア・キーのみを渡せばよいため、安全性の低い形で資格証明をハードコードしたり格納したりする必要がなくなります。UMS Webサービス・クライアントでのSAMLセキュリティの構成の詳細は、例62-1を参照してください。
ユーザー名トークンおよびSAMLトークンによるセキュリティは、リスナー・コールバックWebサービスでもサポートされています。リスナーの登録時に、クライアント・アプリケーションでは、セキュリティ・ポリシーおよびセキュアな接続を確立するのにサーバーで必要となるキーや資格証明の参照情報を指定する、追加のパラメータを指定する必要があります。
例62-16は、ユーザー名トークンによるセキュリティを使用してセキュアなコールバック・エンドポイントを確立する方法を示しています。
例62-16 ユーザー名トークンによるセキュリティの使用によるセキュアなコールバック・エンドポイントの確立
MessagingClient client = new MessagingClient(clientParameters); ... ListenerReference listenerRef = new ListenerReference(); // A web service implementing the oracle.ucs.messaging.ws.Listener // interface must be available at the specified URL. listenerRef.setEndpoint(myCallbackURL); Parameter policyParam = new Parameter(); policyParam.setName(ClientConstants.POLICY_STRING); policyParam.setValue("oracle/wss11_username_token_with_message_protection_client_policy"); listenerRef.getParameters.add(policyParam); // A credential store entry with the specified key must be // provisioned on the server side so it will be available when the callback // is invoked. Parameter csfParam = new Parameter(); csfParam.setName(oracle.wsm.security.util.SecurityConstants.ClientConstants.WSS_CSF_KEY); csfParam.setValue("callback-csf-key"); listenerRef.getParameters.add(csfParam); client.setMessageListener(listenerRef);
JAX-WSスタックによって提供される基礎となるサービスにより、WS MessagingClientクラスのインスタンスはスレッドセーフではありません。そのため、各インスタンスが一度に1つのスレッドでのみ使用されていることを確認する必要があります。
この項では、OTNでOracle User Messaging Serviceが提供するWebサービスAPIを使用して、サンプル・チャット・アプリケーションを作成、デプロイおよび実行する方法を説明します。
注意: Oracle User Messaging Serviceのコード・サンプルに関する詳細を参照したり、サンプルを自分で実行するには、URL:https://soasamples.samplecode.oracle.com/ にあるOracle Technology Networkのコード・サンプル・ページを参照してください。
このページにナビゲートした後は、検索条件の「UMS」を入力して「検索」をクリックすることで、Oracle User Messaging Serviceのコード・サンプルを検出できます。 |
注意: Oracle User Messaging Serviceのアーキテクチャとコンポーネントの詳細は、『Oracle Fusion Middleware Oracle SOA Suiteスタート・ガイド』を参照してください。 |
この項の内容は次のとおりです。
このサンプルは、電子メール、SMSまたはIMを通じてメッセージを送受信するWebベースのチャット・アプリケーションの作成方法を示します。このサンプルでは、サービスWebサービスAPIを使用してユーザー・メッセージング・サーバーと相互作用します。Oracle JDeveloperでアプリケーション・サーバー接続を定義し、アプリケーションをデプロイして実行します。事前作成されたOracle JDeveloperプロジェクトとして提供されるこのアプリケーションには、単純なWebチャット・インタフェースが含まれています。
次の手順を実行して、事前作成されたサンプル・アプリケーションを実行し、デプロイします。
「usermessagingsample-ws-src.zip」を抽出し、usermessagingsample-ws.jwsをOracle JDeveloperで開きます。
Oracle JDeveloperのメイン・ウィンドウにプロジェクトが表示されます。
アプリケーションには1つのWebモジュールが含まれています。アプリケーションのソース・コードもすべて整っています。
Webモジュールで「Oracle UMS Client」ライブラリが使用されていることを確認して、サンプル・アプリケーションのビルド依存性を満たします。
「アプリケーション・ナビゲータ」で、Webモジュール「usermessagingsample-ws-war」を右クリックし、「プロジェクト・プロパティ」を選択します。
左側のペインで、「ライブラリとクラスパス」を選択します。
「OK」をクリックします。
ナビゲーション・ペインでプロジェクトを右クリックし、「新規」を選択して、アプリケーション・サーバー接続を作成します。第62.10項「新規アプリケーション・サーバー接続の作成」の説明に従います。
プロジェクトをデプロイするには、「usermessasgingsample-ws project」→「デプロイ」→「usermessasgingsample-ws」→「デプロイ先」→「SOA_server」の順に選択します(図62-4)。
メッセージBuild Successful
がログに表示されていることを確認します。
メッセージDeployment Finished
がデプロイメント・ログに表示されていることを確認します。
アプリケーションが正常にデプロイされました。
次の手順を実行し、サンプルを実行およびテストします。
Webブラウザを開きます。
次のようにアプリケーションのURLに移動し、ログインします。
http://
host
:
port
/usermessagingsample-ws/
メッセージングWebサービス・サンプルWebページが表示されます(図62-5)。このページには、ナビゲーション・タブ、およびアプリケーションの手順が表示されます。
「構成」をクリックして、次の値を入力します(図62-6)。
Webサービスのエンドポイントを指定します。例: http://example.com:8001/ucs/messaging/webservice
ユーザー名とパスワードを指定します。
ポリシーを指定します(ユーザー・メッセージング・サービスのインスタンスでWS-Securityが有効になっている場合に必要)。
「保存」をクリックします。
「管理」をクリックします。
メッセージを受信するアドレスおよびオプションのキーワードを入力します(図62-7)。
「開始」をクリックします。
メッセージRegistration operation succeeded
が表示されていることを確認します。
「チャット」をクリックします(図62-8)。
図62-8に示す書式で受信者をTo:フィールドに入力します。
メッセージを入力します。
「送信」をクリックします。
メッセージが受信されていることを確認します。
次の手順を実行し、アプリケーション・サーバー接続を作成します。
プロジェクトを右クリックし、「新規」→「接続」→「アプリケーション・サーバー接続」の順に選択して、新規アプリケーション・サーバー接続を作成します(図62-9)。
接続にSOA_server
という名前を付けて、「次へ」をクリックします(図62-10)。
「接続タイプ」に「WebLogic 10.3」を選択します。
認証情報を入力します。ユーザー名の一般的な値はweblogic
です。
「接続」ダイアログで、SOA管理サーバーのホスト名、ポートおよびSSLポートを入力し、WLSドメインのドメイン名を入力します。
「次へ」をクリックします。
「テスト」ダイアログで、「接続のテスト」をクリックします。
メッセージSuccess!
が表示されていることを確認します。
アプリケーション・サーバー接続が作成されました。