ヘッダーをスキップ
Oracle® Fusion Middleware Oracle User Messaging Serviceによるアプリケーションの開発
リリース12c (12.1.2)
E47999-02
  目次へ移動
目次

前
 
次
 

4 ユーザー・メッセージング・サービスWebサービスAPIを使用したメッセージの送受信

この章では、ユーザー・メッセージング・サービス(UMS) WebサービスAPIを使用してアプリケーションを開発する方法について説明します。このAPIは、Fusion Middlewareアプリケーション開発者が、UMSサーバーに関連するリモート・コンテナで実行されるUMSメッセージング・アプリケーションを実装する際の、プログラム上のエントリ・ポイントとして機能します。

この章の内容は次のとおりです。


注意:

Oracle User Messaging Serviceのコード・サンプルに関する詳細を参照したり、サンプルを自分で実行するには、次の場所にあるサンプルを参照してください。

http://www.oracle.com/technetwork/indexes/samplecode/sample-ums-1454424.html


4.1 UMS WebサービスAPIの概要

UMS WebサービスAPIは、機能的にはJava APIと同じです。Webサービス・タイプおよびインタフェースのJAX-WSおよびJAXBバインディングは、対応するJava APIクラスと同じように命名されているものの、別個のパッケージ空間にあります。この2つのAPIのクラスには相互運用性はありません。

UMS WebサービスAPIは、次のようにグループ化されたパッケージで構成されています。

ソース・コードを含むサンプルは、Oracle Technology Network (OTN)から入手できます。

4.2 UMSクライアント・インスタンスの作成とランタイム・パラメータの指定

この項では、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 実行時に指定する構成パラメータ

キー データ型 用途

javax.xml.ws.BindingProvider.ENDPOINT_ADDRESS_PROPERTY

文字列

リモートUMS WSのエンドポイントURL。これは通常「http://<host>:<port>/ucs/messaging/webservice」です。

javax.xml.ws.BindingProvider.USERNAME_PROPERTY

文字列

該当する場合にWS-Securityヘッダーにアサートされるユーザー名。

oracle.ucs.messaging.ws.ClientConstants.POLICIES

文字列[]

クライアントの要求に添付する一連の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クラスの新しいインスタンスを作成する必要があります。

例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」に用意されています。

4.3 メッセージの送信

sendメソッドを起動すると、メッセージがUMSに配信されて適切に処理されます。sendメソッドは、メッセージの配信ステータスを取得したり、リスナーに配信される非同期ステータス通知と関連付けたりするために後でクライアント・アプリケーションで使用できる、String message識別子を戻します。戻されたステータスは、UMSの内部処理と外部ゲートウェイから受信した配信通知に基づいた最新のステータスです。

作成できるメッセージのタイプには、プレーン・テキスト・メッセージ、text/plainパートとtext/htmlパートで構成できるマルチパート・メッセージ、および異なる配信タイプを使用して、複数受信者用の単一メッセージに配信チャネル(DeliveryType)固有のペイロードを作成するメッセージがあります。

4.3.1 メッセージの作成

この項では、作成できる様々なタイプのメッセージについて説明します。

4.3.1.1 プレーン・テキスト・メッセージの作成

例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.3.1.2 テキスト・パートとバイナリ・パートを持つマルチパート/混合メッセージの作成

例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.3.1.3 Text/PlainパートとText/HTMLパートを持つマルチパート/代替メッセージの作成

例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())); 

4.3.1.4 異なる配信タイプを使用した、複数受信者用の単一メッセージへの配信チャネル固有のペイロード作成

メッセージを宛先アドレスに送信する際は、複数のチャネルが関連する場合があります。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);

4.3.2 MessageインタフェースのAPIリファレンス

MessageインタフェースのAPIリファレンスには、Javadocからアクセスできます。

4.3.3 列挙DeliveryTypeのAPIリファレンス

列挙DeliveryTypeのAPIリファレンスには、Javadocからアクセスできます。

4.3.4 メッセージのアドレス指定

この項では、アドレスのタイプおよびAddressオブジェクトの作成方法について説明します。

4.3.4.1 アドレスのタイプ

アドレスには、デバイス・アドレスユーザー・アドレスの2種類があります。デバイス・アドレスには、電子メール・アドレス、インスタント・メッセージ・アドレス、電話番号など、様々なタイプがあります。ユーザー・アドレスは、ユーザー・リポジトリにあるユーザーIDです。

4.3.4.2 Addressオブジェクトの作成

Addressインタフェースで定義するAddressオブジェクトは、MessagingFactoryクラスを使用してメッセージの送信者と受信者のアドレスを指定することで作成できます。

4.3.4.2.1 単一のAddressオブジェクトの作成

例4-7に、単一のAddressオブジェクトを作成するコードを示します。

例4-7 単一のAddressオブジェクトの作成

Address recipient = MessagingFactory.createAddress("Email:john@example.com");
4.3.4.2.2 1つのバッチ内での複数のAddressオブジェクトの作成

例4-8に、1つのバッチ内に複数のAddressオブジェクトを作成するコードを示します。

例4-8 1つのバッチ内での複数のAddressオブジェクトの作成

String[] recipientsStr = {"Email:john@example.com", "IM:john@example.com"};
Address[] recipients = MessagingFactory.createAddress(recipientsStr);
4.3.4.2.3 メッセージへの送信者または受信者のアドレスの追加

例4-9に、送信者または受信者のアドレスをメッセージに追加するコードを示します。

例4-9 メッセージへの送信者または受信者のアドレスの追加

Address sender = MessagingFactory.createAddress("Email:john@example.com");
Address recipient = MessagingFactory.createAddress("Email:jane@example.com");
message.addSender(sender);
message.addRecipient(recipient);

4.3.4.3 フェイルオーバー・アドレスを使用した受信者の作成

例4-10に、フェイルオーバー・アドレスを使用して受信者を作成するコードを示します。

例4-10 フェイルオーバーを使用した単一のAddressオブジェクトの作成

String recipientWithFailoverStr = "Email:john@example.com, IM:john@example.com";
Address recipient = MessagingFactory.createAddress(recipientWithFailoverStr);

4.3.4.4 受信者のタイプ

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オブジェクトを渡します。それに対して受信者タイプを示す文字列が戻されます。

4.3.4.5 MessagingFactoryクラスのAPIリファレンス

MessagingFactoryクラスのAPIリファレンスには、Javadocからアクセスできます。

4.3.4.6 AddressインタフェースのAPIリファレンス

AddressインタフェースのAPIリファレンスには、Javadocからアクセスできます。

4.3.5 ユーザー・プリファレンス・ベースのメッセージング

ユーザー受信者にメッセージを送信(してユーザーのメッセージング・プリファレンスを活用)する際、メッセージで様々なビジネス条件のファクト(現在の値)をメタデータとして渡すことができます。UMSサーバーでは、メッセージで指定されたファクトを、ユーザーのメッセージング・フィルタで指定されているビジネス条件の条件と照合します。


注意:

すべてのファクトはメタデータとしてoracle.sdp.client.Message.NAMESPACE_NOTIFICATION_PREFERENCES名前空間に追加する必要があります。他の名前空間のメタデータは(ユーザー通信プリファレンスの解決においては)無視されます。


図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).

4.4 メッセージ・ステータスの取得

メッセージを送信した後は、Oracle UMSを使用して、メッセージ・ステータスを同期または非同期で取得できます。

4.4.1 メッセージ・ステータスの同期取得

現行ステータスの同期取得を実行するには、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.

4.4.2 メッセージ・ステータスの非同期取得

ステータスを非同期的で取得するには、listener.wsdlに記載されているListener Webサービスがクライアント・アプリケーションで実装されている必要があります。リスナー・エンドポイントの実装方法に制約はありません。たとえば、1つの方法は、javax.xml.ws.Endpoint JAX-WS Service APIを使用してWebサービス・エンドポイントをパブリッシュすることです。このメカニズムはJava SE 6で利用でき、コンシューマはJava EEサーブレット・モジュールを明示的に定義する必要はありません。

ただし、サーブレット・ベースのリスナー実装も可能です。

メッセージを送信する際、クライアント・アプリケーションは、エンドポイントURLおよびSOAPインタフェース名で構成されるリスナー・エンドポイントへの参照を提供できます。ステータスはメッセージの処理中に生成されるため、UMSサーバーはリスナー・エンドポイントのonStatusメソッドを呼び出してクライアント・アプリケーションに通知します。

4.4.2.1 プログラムによるリスナーの作成

リスナーは純粋なプログラムです。リスナーは、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!");
  }
}

4.4.2.2 コールバック・サービスのパブリッシュ

コールバック・サービスをパブリッシュするには、アプリケーション内のWebモジュールのweb.xmlでサーブレットを宣言するか、またはJAX-WSのjavax.xml.ws.Endpointクラスのパブリッシュ・メソッドを使用してプログラムによりWSエンドポイントをパブリッシュします(例4-12)。

例4-12 コールバック・サービスのパブリッシュ

Listener myListener = new MyListener();
String callbackURL = "http://host:port/umswscallback";
Endpoint myEndpoint = javax.xml.ws.Endpoint.publish(callbackURL, myListener);

4.4.2.3 動的にパブリッシュされたエンドポイントの停止

動的にパブリッシュされたエンドポイントを停止するには、Endpoint.publish()から戻されたEndpointオブジェクトでstop()メソッドを呼び出します(例4-13)。

例4-13 動的にパブリッシュされたエンドポイントの停止

// When done, stop the endpoint, ideally in a finally block or other reliable cleanup mechanism
myEndpoint.stop();

4.4.2.4 登録

リスナーWebサービスがパブリッシュされると、そのようなエンドポイントがクライアントにあることを登録する必要があります。MessagingClient APIには次の関連メソッドがあります。

  • setStatusListener(ListenerReference listener)

  • send(Message message, ListenerReference listener, byte[] correlator)

setStatusListener()ではデフォルトのステータス・リスナーを登録し、着信ステータス・メッセージに対してはそのリスナーのコールバックが呼び出されます。send()に渡されたリスナーは、対応するメッセージに関連するステータス更新に対してのみ呼び出されます。

4.5 メッセージの受信

この項では、アプリケーションでメッセージを受信する方法について説明します。

着信メッセージを受信するアプリケーションでは、メッセージの受信者アドレスを表すアクセス・ポイントを1つ以上登録する必要があります。サーバーでは、着信メッセージの受信者アドレスと一連の登録済アクセス・ポイントを照合し、一致したアクセス・ポイントを登録したアプリケーションに、その着信メッセージをルーティングします。アプリケーション側から見ると、メッセージを受信するモードには同期と非同期があります。

4.5.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);

4.5.2 同期受信

メソッドMessagingClient.receiveを使用して、UMSがアプリケーションで使用可能にしたメッセージを同期受信します。このメソッドは、メッセージの非同期受信による構成オーバーヘッドを望まない軽量なクライアント向けの便利なポーリング・メソッドです。

受信は非ブロック操作です。アプリケーションやアクセス・ポイントに関して保留中のメッセージがない場合、該当するコールでは、空のリストが即時に戻されます。受信によって、すべての使用可能なメッセージが戻される保証はありませんが、効率上の理由から使用可能なメッセージのサブセットのみを戻すことはできます。

このメソッドは非ブロック・コールを実行するため、現在使用できるメッセージがない場合はNULLを戻します。


注意:

1回の起動で、使用可能なメッセージがすべて取得される保証はありません。ポーリングして、使用可能なすべてのメッセージを受信したことを確認する必要があります。


4.5.3 非同期受信

メッセージを非同期で受信するには、listener.wsdlに記載されているListener Webサービスがクライアント・アプリケーションで実装されている必要があります。リスナー・エンドポイントの実装方法に制約はありません。たとえば1つのメカニズムは、javax.xml.ws.Endpoint JAX-WS Service APIを使用してWebサービス・エンドポイントをパブリッシュすることです。このメカニズムはJava SE 6で利用でき、コンシューマはJava EEサーブレット・モジュールを明示的に定義する必要はありません。ただし、サーブレット・ベースのリスナー実装も可能です。

4.5.3.1 プログラムによるリスナーの作成

リスナーは純粋なプログラムです。リスナーは、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.5.3.2 デフォルトのメッセージ・リスナー

クライアント・アプリケーションでは通常、デフォルトのメッセージ・リスナー(例4-14)が設定されます。このリスナーは、このクライアント・アプリケーションによって送信されたメッセージの中で、関連するリスナーがないメッセージの配信ステータスに対して起動されます。Oracle UMSでは、このクライアント・アプリケーションによって登録されたアクセス・ポイント宛てのメッセージを受信すると、そのクライアント・アプリケーションのデフォルトのリスナーに対してonMessageコールバックが起動されます。

デフォルトのリスナーを削除するには、nullの引数を指定してこのメソッドをコールします。

例4-14 デフォルトのメッセージ・リスナー

ListenerReference listenerRef = new ListenerReference();
listenerRef.setEndpoint("url_to_your_webservice_message_listener");
messagingClient.setMessageListener(listenerRef);

4.5.3.3 アクセス・ポイントごとのメッセージ・リスナー

クライアント・アプリケーションでは、アクセス・ポイントを登録し、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);

4.5.4 メッセージ・フィルタ

アプリケーションで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);

4.6 クラスタ環境の構成

APIでは、クラスタ環境にクライアント・アプリケーションとUMSサーバーがデプロイされている環境をサポートしています。クラスタ化されたデプロイメントが期待どおりに機能するためには、クライアント・アプリケーションを正しく構成する必要があります。次のルールが適用されます。

4.7 UMS WebサービスAPIを使用したメッセージ再送信の指定

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リファレンスを参照してください。

4.8 セキュリティの構成

次の項ではセキュリティに関する考慮事項が説明されています。

4.8.1 クライアントおよびサーバーのセキュリティ

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を参照してください。

4.8.2 リスナーまたはコールバックのセキュリティ

ユーザー名トークンおよび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);

4.9 スレッド・モデル

JAX-WSスタックによって提供される基礎となるサービスにより、WS MessagingClientクラスのインスタンスはスレッドセーフではありません。そのため、各インスタンスが一度に1つのスレッドでのみ使用されていることを確認する必要があります。

4.10 WebサービスAPIを使用したサンプル・チャット・アプリケーション

この項では、OTNでOracle User Messaging Serviceが提供するWebサービスAPIを使用して、サンプル・チャット・アプリケーションを作成、デプロイおよび実行する方法を説明します。


注意:

Oracle User Messaging Serviceのコード・サンプルに関する詳細を参照したり、サンプルを自分で実行するには、次の場所にあるサンプルを参照してください。

http://www.oracle.com/technetwork/indexes/samplecode/sample-ums-1454424.html


この項の内容は次のとおりです。

4.10.1 概要

このサンプルは、電子メール、SMSまたはIMを通じてメッセージを送受信するWebベースのチャット・アプリケーションの作成方法を示します。このサンプルでは、サービスWebサービスAPIを使用してユーザー・メッセージング・サーバーと相互作用します。Oracle JDeveloperでアプリケーション・サーバー接続を定義し、アプリケーションをデプロイおよび実行します。

このアプリケーションは、単純なWebチャット・インタフェースが含まれる、事前作成されたOracle JDeveloperプロジェクトとして提供されます。


注意:

このサンプルが動作するには、UMSサーバーが使用でき、必要なドライバにより適切に構成されている必要があります。


4.10.1.1 提供されるファイル

サンプル・アプリケーションには、次のファイルが含まれています。

  • usermessagingsample-ws-src.zip - ソース・コードおよびOracle JDeveloperプロジェクト・ファイルが格納されたアーカイブです。

  • usermessagingsample-ws.ear - コンテナにデプロイ可能な、事前作成されたサンプル・アプリケーションです。

4.10.2 事前作成されたサンプルの実行

次の手順を実行して、事前作成されたサンプル・アプリケーションを実行し、デプロイします。

  1. 「usermessagingsample-ws-src.zip」を抽出し、usermessagingsample-ws.jwsをOracle JDeveloperで開きます。

    図4-1 Oracle JDeveloperでプロジェクトを開く

    図4-1の説明が続きます
    「図4-1 Oracle JDeveloperでプロジェクトを開く」の説明

    Oracle JDeveloperのメイン・ウィンドウにプロジェクトが表示されます。

    図4-2 Oracle JDeveloperのメイン・ウィンドウ

    図4-2の説明は図の下のリンクをクリックしてください。
    「図4-2 Oracle JDeveloperのメイン・ウィンドウ」の説明

    このアプリケーションには、1つのWebモジュールが含まれています。アプリケーションのソース・コードはすべて設定済です。

  2. Webモジュールで「Oracle UMS Client」ライブラリが使用されていることを確認して、サンプル・アプリケーションのビルド依存性を満たします。

    1. 「アプリケーション・ナビゲータ」で、Webモジュール「usermessagingsample-ws-war」を右クリックし、「プロジェクト・プロパティ」を選択します。

    2. 左側のペインで、「ライブラリとクラスパス」を選択します。

      図4-3 ライブラリの追加

      図4-3の説明が続きます
      「図4-3 ライブラリの追加」の説明

    3. 「OK」をクリックします。

  3. ナビゲーション・ペインでプロジェクトを右クリックし、「新規」を選択して、アプリケーション・サーバー接続を作成します。第4.10.4項「新規アプリケーション・サーバー接続の作成」の説明に従います。

  4. プロジェクトをデプロイするには、「usermessasgingsample-ws project」「デプロイ」「usermessasgingsample-ws」「デプロイ先」「SOA_server」の順に選択します(図4-4)。

    図4-4 プロジェクトのデプロイ

    図4-4の説明が続きます
    「図4-4 プロジェクトのデプロイ」の説明

  5. メッセージBuild Successfulがログに表示されていることを確認します。

  6. メッセージDeployment Finishedがデプロイメント・ログに表示されていることを確認します。

    アプリケーションが正常にデプロイされました。

4.10.3 サンプルのテスト

次の手順を実行し、サンプルを実行およびテストします。

  1. Webブラウザを開きます。

  2. 次のようにアプリケーションのURLに移動し、ログインします。

    http://host:port/usermessagingsample-ws/

    メッセージングWebサービス・サンプルWebページが表示されます(図4-5)。このページには、ナビゲーション・タブ、およびアプリケーションの手順が表示されます。

    図4-5 メッセージングWebサービス・サンプルWebページ

    図4-5の説明が続きます
    「図4-5 メッセージングWebサービス・サンプルWebページ」の説明

  3. 「構成」をクリックして、次の値を入力します(図4-6)。

    • Webサービスのエンドポイントを指定します。例: http://example.com:8001/ucs/messaging/webservice

    • ユーザー名とパスワードを指定します。

    • ポリシーを指定します(ユーザー・メッセージング・サービスのインスタンスでWS-Securityが有効になっている場合に必要)。

    • 図4-6 Webサービスのエンドポイントおよび資格証明の構成

      図4-6の説明が続きます
      「図4-6 Webサービスのエンドポイントおよび資格証明の構成」の説明

  4. 「保存」をクリックします。

  5. 「管理」をクリックします。

  6. メッセージを受信するアドレスおよびオプションのキーワードを入力します(図4-7)。

    図4-7 アクセス・ポイントの登録

    図4-7の説明が続きます
    「図4-7 アクセス・ポイントの登録」の説明

  7. 「開始」をクリックします。

    メッセージRegistration operation succeededが表示されていることを確認します。

  8. 「チャット」をクリックします。

  9. 「至」フィールドに受信者を入力します。

  10. メッセージを入力します。

  11. 「送信」をクリックします。

  12. メッセージが受信されていることを確認します。

4.10.4 新規アプリケーション・サーバー接続の作成

Oracle JDeveloperでアプリケーション・サーバー接続を定義し、アプリケーションをデプロイおよび実行します。第A.3項「新規アプリケーション・サーバー接続の作成」の手順を実行し、アプリケーション・サーバー接続を作成します。