| Oracle® Fusion Middleware Oracle User Messaging Serviceによるアプリケーションの開発 リリース12c (12.1.2) E47999-02 |
|
 前 |
 次 |
| Oracle® Fusion Middleware Oracle User Messaging Serviceによるアプリケーションの開発 リリース12c (12.1.2) E47999-02 |
|
前 |
次 |
この章では、ユーザー・メッセージング・サービス(UMS) WebサービスAPIを使用してアプリケーションを開発する方法について説明します。このAPIは、Fusion Middlewareアプリケーション開発者が、UMSサーバーに関連するリモート・コンテナで実行されるUMSメッセージング・アプリケーションを実装する際の、プログラム上のエントリ・ポイントとして機能します。
この章の内容は次のとおりです。
|
注意: Oracle User Messaging Serviceのコード・サンプルに関する詳細を参照したり、サンプルを自分で実行するには、次の場所にあるサンプルを参照してください。
|
UMS WebサービスAPIは、機能的にはJava APIと同じです。Webサービス・タイプおよびインタフェースのJAX-WSおよびJAXBバインディングは、対応するJava APIクラスと同じように命名されているものの、別個のパッケージ空間にあります。この2つのAPIのクラスには相互運用性はありません。
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で認識されるパラメータはいずれも有効です。表4-1に、最も一般的な構成パラメータを示します。
表4-1 実行時に指定する構成パラメータ
| キー | データ型 | 用途 |
|---|---|---|
|
|
文字列 |
リモートUMS WSのエンドポイントURL。これは通常「http://<host>:<port>/ucs/messaging/webservice」です。 |
|
|
文字列 |
該当する場合にWS-Securityヘッダーにアサートされるユーザー名。 |
|
|
文字列[] |
クライアントの要求に添付する一連のOWSM WS-Securityポリシー。サーバー側で指定されたポリシーと一致する必要があります。 |
|
|
文字列 |
OWSMポリシーのアタッチに使用されます。資格証明ストアからの暗号化キーおよび署名キーの参照に使用する代替エイリアスを指定します。 |
|
|
文字列 |
OWSMポリシーのアタッチに使用されます。Oracle Web Services Management資格証明ストア・マップからのリモート・ユーザー名/パスワード情報の参照に使用する資格証明ストア・キーを指定します。 |
インスタンス化された後のMessagingClientは、再構成できません。かわりに、新しい構成を使用してMessagingClientクラスの新しいインスタンスを作成する必要があります。
例4-1に、ユーザー名/トークンによるセキュリティを使用して、プログラミングによってMessagingClientインスタンスを作成する場合のコードを示します。
例4-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);
例4-2に、SAMLトークンによるセキュリティを使用して、プログラミングによってMessagingClientインスタンスを作成する場合のコードを示します。
例4-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)固有のペイロードを作成するメッセージがあります。
この項では、作成できる様々なタイプのメッセージについて説明します。
例4-3に、UMS WebサービスAPIを使用してプレーン・テキスト・メッセージを作成する2つの方法を示します。
例4-3 UMS WebサービスAPIを使用したプレーン・テキスト・メッセージの作成
Message message = MessagingFactory.createTextMessage("This is a Plain Text
message.");
or
Message message = MessagingFactory.createMessage();
message.setContent(new DataHandler(new StringDataSource("This is a Plain Text
message.", "text/plain; charset=UTF-8")));
例4-4に、UMS WebサービスAPIを使用してマルチパート/混合メッセージを作成する方法を示します。
例4-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()));
例4-5に、UMS WebサービスAPIを使用してマルチパート/代替メッセージを作成する方法を示します。
例4-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アプリケーション開発者は、各チャネルに対して正しいマルチパート書式を指定する必要があります。
例4-6に、異なる配信タイプを使用して、複数受信者用の単一メッセージに、配信チャネル(DeliveryType)固有のペイロードを作成する方法を示します。
複数ペイロードのマルチパート/代替メッセージの各最上位パートには、このヘッダーの値が1つ以上含まれている必要があります。このヘッダーの値は、有効な配信タイプの名前である必要があります。DeliveryTypeの使用可能な値は、列挙DeliveryTypeを参照してください。
例4-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.client.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サーバーでは、メッセージで指定されたファクトを、ユーザーのメッセージング・フィルタで指定されているビジネス条件の条件と照合します。
|
注意: すべてのファクトはメタデータとして |
図4-11は、ユーザー受信者を指定し、メッセージのユーザー・プリファレンスでビジネス条件のファクトを指定する方法を示します。サポートされているビジネス条件の完全なリストは、第6章「ユーザー通信プリファレンス」を参照してください。
例4-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.client.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エンドポイントをパブリッシュします(例4-12)。
動的にパブリッシュされたエンドポイントを停止するには、Endpoint.publish()から戻されたEndpointオブジェクトでstop()メソッドを呼び出します(例4-13)。
リスナーWebサービスがパブリッシュされると、そのようなエンドポイントがクライアントにあることを登録する必要があります。MessagingClient APIには次の関連メソッドがあります。
setStatusListener(ListenerReference listener)
send(Message message, ListenerReference listener, byte[] correlator)
setStatusListener()ではデフォルトのステータス・リスナーを登録し、着信ステータス・メッセージに対してはそのリスナーのコールバックが呼び出されます。send()に渡されたリスナーは、対応するメッセージに関連するステータス更新に対してのみ呼び出されます。
この項では、アプリケーションでメッセージを受信する方法について説明します。
着信メッセージを受信するアプリケーションでは、メッセージの受信者アドレスを表すアクセス・ポイントを1つ以上登録する必要があります。サーバーでは、着信メッセージの受信者アドレスと一連の登録済アクセス・ポイントを照合し、一致したアクセス・ポイントを登録したアプリケーションに、その着信メッセージをルーティングします。アプリケーション側から見ると、メッセージを受信するモードには同期と非同期があります。
クライアント・アプリケーションではアクセス・ポイントを作成して登録し、特定のアドレスに送信された着信メッセージを受信するように指定できます。
この場合、クライアント・アプリケーションでは、受信メソッドを起動して保留中のメッセージをフェッチできます。アクセス・ポイントの指定なしでメッセージを受信した場合、アプリケーションでは、登録したすべてのアクセス・ポイントのメッセージを受信します。そうでない場合、アプリケーションでは、そのアクセス・ポイントに送信されたメッセージを受信します。
AccessPointは、着信メッセージを受信するための1つ以上のデバイス・アドレスを表します。
MessagingFactory.createAccessPointを使用してアクセス・ポイントを作成し、そのアクセス・ポイントをMessagingClient.registerAccessPointを使用してメッセージ受信用に登録できます。
電子メールのアクセス・ポイントを登録するには、次のように指定します。
Address apAddress = MessagingFactory.createAddress("EMAIL:user1@example.com");
AccessPoint ap = MessagingFactory.createAccessPoint(apAddress);
MessagingClient.registerAccessPoint(ap);
番号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を使用して、UMSがアプリケーションで使用可能にしたメッセージを同期受信します。このメソッドは、メッセージの非同期受信による構成オーバーヘッドを望まない軽量なクライアント向けの便利なポーリング・メソッドです。
受信は非ブロック操作です。アプリケーションやアクセス・ポイントに関して保留中のメッセージがない場合、該当するコールでは、空のリストが即時に戻されます。受信によって、すべての使用可能なメッセージが戻される保証はありませんが、効率上の理由から使用可能なメッセージのサブセットのみを戻すことはできます。
このメソッドは非ブロック・コールを実行するため、現在使用できるメッセージがない場合は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メソッドが起動されます。
クライアント・アプリケーションでは通常、デフォルトのメッセージ・リスナー(例4-14)が設定されます。このリスナーは、このクライアント・アプリケーションによって送信されたメッセージの中で、関連するリスナーがないメッセージの配信ステータスに対して起動されます。Oracle UMSでは、このクライアント・アプリケーションによって登録されたアクセス・ポイント宛てのメッセージを受信すると、そのクライアント・アプリケーションのデフォルトのリスナーに対してonMessageコールバックが起動されます。
デフォルトのリスナーを削除するには、nullの引数を指定してこのメソッドをコールします。
クライアント・アプリケーションでは、アクセス・ポイントを登録し、Listenerオブジェクトとオプションの相関機能オブジェクトを指定できます(例4-15)。受信メッセージが指定のアクセス・ポイント・アドレスに着信すると、指定したリスナーのonMessageメソッドが起動されます。当初指定の相関機能オブジェクトもコールバック・メソッドに渡されます。
例4-15 アクセス・ポイントごとのメッセージ・リスナー
AccessPoint accessPoint =
MessagingFactory.createAccessPoint(AccessPointType.SINGLE_ADDRESS,
DeliveryType.EMAIL, "test@example.org");
ListenerReference listenerRef = new ListenerReference();
listenerRef.setEndpoint("url_to_your_webservice_message_listener");
byte[] correlator = null; // Not to correlate the callback
messagingClient.registerAccessPoint(accessPoint, listenerRef, correlator);
アプリケーションで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では、メッセージ送信が失敗した場合のメッセージ再送信をスケジュールできます。次の例に示されているように、setMaxResendメソッドをコールすることにより、メッセージ再送信の最大回数を指定できます。
MessageInfo msgInfo = new oracle.ucs.messages.ws.types.MessageInfo(); msgInfo.setMaxResend(new Integer(1)); // When MessageInfo is created we must also set priority msgInfo.setPriority(PriorityType.NORMAL); message.setMessageInfo(msgInfo); String mid = client.send(message, null, null);
フェイルオーバー・アドレスのステータスは、getTotalFailovers()およびgetFailoverOrder()のコールにより受信できます。フェイルオーバーの順序がフェイルオーバー総数と同じになると、APIユーザーには、フェイルオーバー・チェーンがすべて使用済であることがわかります。ただし、再送信機能は、フェイルオーバー・チェーンのループとして動作します。getMaxResend()とgetCurrentResend()をコールして、再送信とフェイルオーバー・チェーンがすべて使用済となるタイミングを知ることができます。
setMaxResendメソッド、getTotalFailoversメソッドおよびgetFailoverOrderメソッドの詳細は、ユーザー・メッセージング・サービスJava APIリファレンスを参照してください。
次の項ではセキュリティに関する考慮事項が説明されています。
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セキュリティの構成の詳細は、例4-2を参照してください。
サポートされているユーザー名トークン・ポリシーは"oracle/wss11_username_token_with_message_protection_client_policy"です。このポリシーがWS-Securityヘッダーで暗号化されたユーザー名/パスワードのトークンを渡し、指定された資格証明をサーバーが認証します。ユーザー名とパスワードは資格証明ストアに格納することをお薦めします。こうすると、MessagingClientコンストラクタには資格証明ストア・キーのみを渡せばよいため、安全性の低い形で資格証明をハードコードしたり格納したりする必要がなくなります。UMS Webサービス・クライアントでのSAMLセキュリティの構成の詳細は、例4-1を参照してください。
ユーザー名トークンおよびSAMLトークンによるセキュリティは、リスナー・コールバックWebサービスでもサポートされています。リスナーの登録時に、クライアント・アプリケーションでは、セキュリティ・ポリシーおよびセキュアな接続を確立するのにサーバーで必要となるキーや資格証明の参照情報を指定する、追加のパラメータを指定する必要があります。
例4-16は、ユーザー名トークンによるセキュリティを使用してセキュアなコールバック・エンドポイントを確立する方法を示しています。
例4-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のコード・サンプルに関する詳細を参照したり、サンプルを自分で実行するには、次の場所にあるサンプルを参照してください。
|
この項の内容は次のとおりです。
このサンプルは、電子メール、SMSまたはIMを通じてメッセージを送受信するWebベースのチャット・アプリケーションの作成方法を示します。このサンプルでは、サービスWebサービスAPIを使用してユーザー・メッセージング・サーバーと相互作用します。Oracle JDeveloperでアプリケーション・サーバー接続を定義し、アプリケーションをデプロイおよび実行します。
このアプリケーションは、単純なWebチャット・インタフェースが含まれる、事前作成されたOracle JDeveloperプロジェクトとして提供されます。
|
注意: このサンプルが動作するには、UMSサーバーが使用でき、必要なドライバにより適切に構成されている必要があります。 |
次の手順を実行して、事前作成されたサンプル・アプリケーションを実行し、デプロイします。
「usermessagingsample-ws-src.zip」を抽出し、usermessagingsample-ws.jwsをOracle JDeveloperで開きます。
Oracle JDeveloperのメイン・ウィンドウにプロジェクトが表示されます。
このアプリケーションには、1つのWebモジュールが含まれています。アプリケーションのソース・コードはすべて設定済です。
Webモジュールで「Oracle UMS Client」ライブラリが使用されていることを確認して、サンプル・アプリケーションのビルド依存性を満たします。
「アプリケーション・ナビゲータ」で、Webモジュール「usermessagingsample-ws-war」を右クリックし、「プロジェクト・プロパティ」を選択します。
左側のペインで、「ライブラリとクラスパス」を選択します。
「OK」をクリックします。
ナビゲーション・ペインでプロジェクトを右クリックし、「新規」を選択して、アプリケーション・サーバー接続を作成します。第4.10.4項「新規アプリケーション・サーバー接続の作成」の説明に従います。
プロジェクトをデプロイするには、「usermessasgingsample-ws project」→「デプロイ」→「usermessasgingsample-ws」→「デプロイ先」→「SOA_server」の順に選択します(図4-4)。
メッセージBuild Successfulがログに表示されていることを確認します。
メッセージDeployment Finishedがデプロイメント・ログに表示されていることを確認します。
アプリケーションが正常にデプロイされました。
次の手順を実行し、サンプルを実行およびテストします。
Webブラウザを開きます。
次のようにアプリケーションのURLに移動し、ログインします。
http://host:port/usermessagingsample-ws/
メッセージングWebサービス・サンプルWebページが表示されます(図4-5)。このページには、ナビゲーション・タブ、およびアプリケーションの手順が表示されます。
「構成」をクリックして、次の値を入力します(図4-6)。
Webサービスのエンドポイントを指定します。例: http://example.com:8001/ucs/messaging/webservice
ユーザー名とパスワードを指定します。
ポリシーを指定します(ユーザー・メッセージング・サービスのインスタンスでWS-Securityが有効になっている場合に必要)。
「保存」をクリックします。
「管理」をクリックします。
メッセージを受信するアドレスおよびオプションのキーワードを入力します(図4-7)。
「開始」をクリックします。
メッセージRegistration operation succeededが表示されていることを確認します。
「チャット」をクリックします。
「至」フィールドに受信者を入力します。
メッセージを入力します。
「送信」をクリックします。
メッセージが受信されていることを確認します。
Oracle JDeveloperでアプリケーション・サーバー接続を定義し、アプリケーションをデプロイおよび実行します。第A.3項「新規アプリケーション・サーバー接続の作成」の手順を実行し、アプリケーション・サーバー接続を作成します。
