この章では、ユーザー・メッセージング・サービス(UMS)クライアントAPIを使用してアプリケーションを開発する方法について説明します。このAPIは、Fusion Middlewareアプリケーション開発者がメッセージ機能をエンタープライズ・アプリケーション内に組み込む際のプログラム上のエントリ・ポイントとして機能します。
このAPIには、Plain Old Java (POJO/POJI)プログラミング・モデルが用意されているため、アプリケーション開発者は、UMS機能にアクセスするためにアプリケーションで様々なJava EEモジュール(EJBモジュールなど)をパッケージ化して実装する必要がありません。開発者はモジュールの追加パッケージ化を実行したり、パッケージ・タスクを実行するための特別なツールを取得せずに、Java EEコンテナで実行するアプリケーションを作成できるため、開発時間が削減されます。
UMS Java APIのコンシューマは、環境エントリや他のJava EEデプロイメント・ディスクリプタ・アーティファクトなどのJava EEメカニズムを使用する必要がありません。Java EEディスクリプタの管理に関するオーバーヘッドの他に、多くのクライアント・アプリケーションには、Java EEディスクリプタに依存しない構成フレームワークがあります。
この章では、次の項目について説明します。
注意: Oracle User Messaging Serviceのコード・サンプルに関する詳細を参照したり、サンプルを自分で実行するには、次の場所にあるサンプルを参照してください。
|
UMS Java APIは、POJO/POJI APIとして公開されています。このAPIのコンシューマは、ファクトリ・メソッドを使用してMessagingClient
オブジェクトのインスタンスを取得できます。コンシューマは、EJBや他のJava EEモジュールをそれぞれのアプリケーションにデプロイする必要はありませんが、アプリケーションのランタイム・クラスパスでUMSライブラリが使用可能であることを確認する必要があります。デプロイメントは、共有ライブラリ「oracle.sdp.client」としてです。
UMS Java APIは、次のようにグループ化されたパッケージで構成されています。
共通およびクライアントのパッケージ
oracle.sdp.messaging
oracle.sdp.messaging.filter
: アプリケーションでMessageFilterを使用すると、配信されるメッセージをより強力に制御できます。
ソース・コードを含むサンプルは、Oracle Technology Network (OTN)から入手できます。
この項では、UMSクライアントを作成するための要件を説明します。MessagingClient
インスタンスは、MessagingClientFactoryクラスのコードを使用して作成できます。具体的には、このインスタンスの作成にはMessagingClientFactory.createMessagingClient()
メソッドを使用します。
クライアント・アプリケーションでは、クライアント・オブジェクトのインスタンス化の実行時に一連のパラメータを指定できます。たとえば、MessagingClient
インスタンスを構成するには、複数のパラメータをキーと値のペアのマップとしてjava.util.Map<String, Object>
に指定します。特に、これらの構成パラメータは、クライアント・アプリケーションの識別、UMSサーバーの指定およびセキュリティ資格証明の確立に役立ちます。クライアント・アプリケーションでは、使用可能なメカニズムを使用して構成パラメータを保存およびロードする必要があります。
表64-1に、Java APIに設定可能な構成パラメータの一部を示します。通常のユースケースでは、ほとんどのパラメータは指定する必要がなく、APIの実装では適切なデフォルト値が使用されます。
表64-1 実行時に指定する構成パラメータ
パラメータ | ノート |
---|---|
|
オプション。デフォルトでは、クライアントはそのデプロイメント名で識別されます。この識別子は、 |
|
オプション。指定が必要なのは、クラスタ化された特定のユースケースの場合か、セッションベースのルーティングを利用する場合のみです。 |
|
オプション。デフォルトでは、クライアントのリソースは、同じアプリケーション名のすべてのアプリケーションおよびすべてのセキュリティ・プリンシパルで使用できます。この動作は、 |
|
オプション。メッセージまたはステータスの非同期受信にリスナーを使用する場合、リスナー・ワーカー・スレッドの数は、 |
|
オプション。メッセージの受信時には、 |
MessagingClient
インスタンスで使用するリソースが不要となったときに解放するには、MessagingClientFactory.remove(client)
をコールします。このメソッドをコールしない場合は、ワーカー・スレッドやJMSリスナーなど一部のリソースがアクティブのまま残る場合があります。
例64-1に、プログラミングによってMessagingClient
インスタンスを作成する場合のコードを示します。
例64-1 プログラミングによるMessagingClientインスタンスの作成
Map<String, Object> params = new HashMap<String, Object>(); // params.put(key, value); // if optional parameters need to be specified. MessagingClient messagingClient = MessagingClientFactory.createMessagingClient(params);
インスタンス化された後のMessagingClient
は、再構成できません。かわりに、任意の構成を使用してMessagingClient
クラスの新しいインスタンスを作成する必要があります。
クライアント・アプリケーションでは、次に示すもののMessagingFactory
クラスを使用してメッセージ・オブジェクトを作成できます: oracle.sdp.messaging
.MessagingFactory
。このクラスの他のメソッドを使用して、Addresses
、AccessPoints
、MessageFilters
およびMessageQueries
を作成できます。これらのメソッドの詳細は、Javadocを参照してください。
これで、クライアント・アプリケーションではメッセージを送信できます。APIは、メッセージの配信ステータスを取得するために後でクライアント・アプリケーションで使用できる文字列識別子を戻します。戻されたステータスは、UMSの内部処理と外部ゲートウェイから受信した配信通知に基づいた最新のステータスです。
作成できるメッセージのタイプには、プレーン・テキスト・メッセージ、text/plainパートとtext/htmlパートで構成できるマルチパート・メッセージ、および異なる配信タイプを使用して、複数受信者用の単一メッセージに配信チャネル(DeliveryType
)固有のペイロードを作成するメッセージがあります。
この項の内容は次のとおりです。
この項では、作成できる様々なタイプのメッセージについて説明します。
例64-2に、UMS Java APIを使用してプレーン・テキスト・メッセージを作成する方法を示します。
例64-3に、UMS Java APIを使用してマルチパート・メッセージまたは代替メッセージを作成する方法を示します。
例64-3 UMS Java APIを使用したマルチパート・メッセージまたは代替メッセージの作成
Message message = MessagingFactory.createMessage(); MimeMultipart mp = new MimeMultipart("alternative"); MimeBodyPart mp_partPlain = new MimeBodyPart(); mp_partPlain.setContent("This is a Plain Text part.", "text/plain"); mp.addBodyPart(mp_partPlain); MimeBodyPart mp_partRich = new MimeBodyPart(); mp_partRich .setContent( "<html><head></head><body><b><i>This is an HTML part.</i></b></body></html>", "text/html"); mp.addBodyPart(mp_partRich); message.setContent(mp, "multipart/alternative");
メッセージを宛先アドレスに送信する際は、複数のチャネルが関連する場合があります。Oracle UMSアプリケーション開発者は、各チャネルに対して正しいマルチパート書式を指定する必要があります。
例64-4に、異なる配信タイプを使用して、複数受信者用の単一メッセージに、配信チャネル(DeliveryType
)固有のペイロードを作成する方法を示します。
複数ペイロードのマルチパート/代替メッセージの各最上位パートには、このヘッダーの値が1つ以上含まれている必要があります。このヘッダーの値は、有効な配信タイプの名前である必要があります。DeliveryTypeの使用可能な値は、列挙DeliveryType
を参照してください。
例64-4 異なる配信タイプを使用した、複数受信者用の単一メッセージへの配信チャネル固有のペイロード作成
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.setContent("Text content for SMS.", "text/plain"); 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.setContent("Text content for EMAIL/IM.", "text/plain"); part2_mp.addBodyPart(part2_mp_partPlain); MimeBodyPart part2_mp_partRich = new MimeBodyPart(); part2_mp_partRich.setContent("<html><head></head><body><b><i>" + "HTML content for EMAIL/IM." + "</i></b></body></html>", "text/html"); part2_mp.addBodyPart(part2_mp_partRich); part2.setContent(part2_mp, "multipart/alternative"); 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(mp, "multipart/alternative"); // set the MultiplePayload flag to true message.setMultiplePayload(true);
MessagingFactory
クラスのAPIリファレンスには、Javadocからアクセスできます。
MessageインタフェースのAPIリファレンスには、Javadocからアクセスできます。
列挙DeliveryType
のAPIリファレンスには、Javadocからアクセスできます。
この項では、アドレスのタイプおよびAddressオブジェクトの作成方法について説明します。
アドレスには、デバイス・アドレスとユーザー・アドレスの2種類があります。デバイス・アドレスには、電子メール・アドレス、インスタント・メッセージ・アドレス、電話番号など、様々なタイプがあります。ユーザー・アドレスは、ユーザー・リポジトリにあるユーザーIDです。
Address
インタフェースで定義するAddress
オブジェクトは、MessagingFactory
クラスを使用してメッセージの送信者と受信者のアドレスを指定することで作成できます。
ユーザー受信者にメッセージを送信(してユーザーのメッセージング・プリファレンスを活用)する際、メッセージで様々なビジネス条件の現在の値をメタデータとして渡すことができます。UMSサーバーでは、メッセージで指定されたファクトを、ユーザーのメッセージング・フィルタで指定されているビジネス条件の条件と照合します。
注意: すべてのファクトはメタデータとしてMessage.NAMESPACE_NOTIFICATION_PREFERENCES 名前空間に追加する必要があります。他の名前空間のメタデータは(ユーザー・メッセージング・プリファレンスの解決においては)無視されます。 |
図64-9は、ユーザー受信者を指定し、メッセージのユーザー・プリファレンスでビジネス条件のファクトを指定する方法を示します。サポートされているビジネス条件の完全なリストは、第67章「ユーザー・メッセージング・プリファレンス」を参照してください。
例64-9 ユーザー・プリファレンス・ベースのメッセージング
Message message = MessagingFactory.createMessage(); // create and add a user recipient Address userRecipient1 = MessagingFactory.createAddress("USER:sampleuser1"); message.addRecipient(userRecipient1); // specify business term facts message.setMetaData(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); Status[] statuses = messagingClient.getStatus(messageId);
または、
Status[] statuses = messagingClient.getStatus(messageId, address[]) --- where address[] is an array of one or more of the recipients set in the message.
ステータスを非同期で受信する場合は、クライアント・アプリケーションによってListener
オブジェクトとオプションの相関機能オブジェクトが指定されます。受信ステータスが着信すると、リスナーのonStatus
コールバックが起動されます。当初指定の相関機能オブジェクトもコールバック・メソッドに渡されます。
リスナーは純粋なプログラムです。リスナーは、oracle.sdp.messaging.Listener
インタフェースを実装して作成します。このインタフェースは、具体クラス(既存クラスの1つ、新規クラス、あるいは無名クラスか内部クラス)として実装できます。
次のコード例は、ステータス・リスナーの実装方法を示しています。
import oracle.sdp.messaging.Listener; public class StatusListener implements Listener { @Override public void onMessage(Message message, Serializable correlator) { } @Override public void onStatus(Status status, Serializable correlator) { System.out.println("Received Status: " + status + " with optional correlator: " + correlator); } }
Listener
オブジェクトへの参照は、「デフォルトのステータス・リスナー」
および「メッセージごとのステータス・リスナー」
の説明に従って、setStatusListenerまたはsendメソッドに渡します。メッセージのステータスが着信すると、UMSインフラストラクチャでは、リスナーのonStatus
メソッドが必要に応じて起動されます。
クライアント・アプリケーションでは通常、デフォルトのステータス・リスナー(例64-10)が設定されます。クライアント・アプリケーションでメッセージが送信されると、そのメッセージの配信ステータス・コールバックによって、デフォルト・リスナーのonStatus
メソッドが起動されます。
この方法では、クライアント・アプリケーションによってメッセージが送信され、リスナー・オブジェクトとオプションの相関機能オブジェクトが指定されます(例64-11)。該当するメッセージに対して配信ステータス・コールバックが使用できる場合は、指定したリスナーのonStatus
メソッドが起動されます。当初指定の相関機能オブジェクトもコールバック・メソッドに渡されます。
この項では、アプリケーションでメッセージを受信する方法について説明します。メッセージを受信するには、最初にアクセス・ポイントを登録する必要があります。アプリケーション側から見ると、メッセージを受信するモードには同期と非同期があります。
クライアント・アプリケーションではアクセス・ポイントを作成して登録し、特定のアドレスに送信された着信メッセージを受信するように指定できます。クライアント・アプリケーションにはメッセージ・リスナーが指定されていないため、受信したすべてのメッセージはUMSに保持されます。この場合、クライアント・アプリケーションでは、受信メソッドを起動して保留中のメッセージをフェッチできます。アクセス・ポイントの指定なしでメッセージを受信した場合、アプリケーションでは、登録したすべてのアクセス・ポイントのメッセージを受信します。アクセス・ポイントが指定されている場合、アプリケーションでは、そのアクセス・ポイントに送信されたメッセージを受信します。
AccessPoint
は、着信メッセージを受信するための1つ以上のデバイス・アドレスを表します。着信メッセージを受信するアプリケーションでは、メッセージの受信者アドレスを表すアクセス・ポイントを1つ以上登録する必要があります。サーバーでは、着信メッセージの受信者アドレスと一連の登録済アクセス・ポイントを照合し、一致したアクセス・ポイントを登録したアプリケーションに、その着信メッセージをルーティングします。
MessagingFactory.createAccessPoint
を使用してアクセス・ポイントを作成し、そのアクセス・ポイントをMessagingClient.registerAccessPoint
を使用してメッセージ受信用に登録できます。
番号9000
のSMSアクセス・ポイントを登録するには、次のように指定します。
AccessPoint accessPointSingleAddress = MessagingFactory.createAccessPoint(AccessPoint.AccessPointType.SINGLE_ADDRESS, DeliveryType.SMS, "9000"); messagingClient.registerAccessPoint(accessPointSingleAddress);
番号が9000
から9999
の範囲内のSMSアクセス・ポイントを登録するには、次のように指定します。
AccessPoint accessPointRangeAddress = MessagingFactory.createAccessPoint(AccessPoint.AccessPointType.NUMBER_RANGE, DeliveryType.SMS,"9000,9999"); messagingClient.registerAccessPoint(accessPointRangeAddress);
受信は非ブロック操作です。アプリケーションやアクセス・ポイントに関して保留中のメッセージがない場合、該当するコールでは、空のリストが即時に戻されます。受信によって、すべての使用可能なメッセージが戻される保証はありませんが、効率上の理由から使用可能なメッセージのサブセットのみを戻すことはできます。
メッセージの同期受信には、メソッドMessagingClient.receive
を使用できます。このメソッドは、メッセージの非同期受信による構成オーバーヘッドを望まない軽量なクライアント向けの便利なポーリング・メソッドです。このメソッドは、アプリケーションのインバウンド・キューですぐに使用できるメッセージのリストを戻します。
このメソッドは非ブロック・コールを実行するため、現在使用できるメッセージがない場合はNULLを戻します。
注意: 1回の起動で、使用可能なメッセージがすべて取得される保証はありません。ポーリングして、使用可能なすべてのメッセージを受信したことを確認する必要があります。 |
メッセージを非同期で受信する場合は、クライアント・アプリケーションによってアクセス・ポイントが登録され、Listener
オブジェクトとオプションの相関機能オブジェクトが指定されます。受信メッセージが指定のアクセス・ポイント・アドレスに着信すると、リスナーのonMessage
コールバックが起動されます。当初指定の相関機能オブジェクトもコールバック・メソッドに渡されます。
リスナーは純粋なプログラムです。リスナーは、oracle.sdp.messaging.Listener
インタフェースを実装して作成します。このインタフェースは、具体クラス(既存クラスの1つ、新規クラス、あるいは無名クラスか内部クラス)として実装できます。
次のコード例は、メッセージ・リスナーの実装方法を示しています。
import oracle.sdp.messaging.Listener; public class MyListener implements Listener { @Override public void onMessage(Message message, Serializable correlator) { System.out.println("Received Message: " + message + " with optional correlator: " + correlator); } @Override public void onStatus(Status status, Serializable correlator) { System.out.println("Received Status: " + status + " with optional correlator: " + correlator); } }
リスナー・オブジェクトへの参照は、「デフォルトのメッセージ・リスナー」
および「アクセス・ポイントごとのメッセージ・リスナー」
の説明に従って、setMessageListenerまたはregisterAccessPointメソッドに渡します。アプリケーションのメッセージが着信すると、UMSインフラストラクチャでは、リスナーのonMessage
メソッドが起動されます。
クライアント・アプリケーションでは通常、デフォルトのメッセージ・リスナー(例64-12)が設定されます。このリスナーは、このクライアント・アプリケーションによって送信されたメッセージの中で、関連するリスナーがないメッセージの配信ステータスに対して起動されます。Oracle UMSでは、このクライアント・アプリケーションによって登録されたアクセス・ポイント宛てのメッセージを受信すると、そのクライアント・アプリケーションのデフォルトのリスナーに対してonMessage
コールバックが起動されます。
デフォルトのリスナーを削除するには、nullの引数を指定してこのメソッドをコールします。
非同期受信の詳細な手順については、サンプル・アプリケーションusermessagingsample-echo
を参照してください。
クライアント・アプリケーションでは、アクセス・ポイントを登録し、Listener
オブジェクトとオプションの相関機能オブジェクトを指定できます(例64-13)。受信メッセージが指定のアクセス・ポイント・アドレスに着信すると、指定したリスナーのonMessage
メソッドが起動されます。当初指定の相関機能オブジェクトもコールバック・メソッドに渡されます。
アプリケーションでMessageFilter
を使用すると、配信されるメッセージをより強力に制御できます。MessageFilter
には、一致基準とアクションが含まれています。アプリケーションでは、一連のメッセージ・フィルタを登録できます。登録されたメッセージ・フィルタは、着信(受信)メッセージに順に適用され、メッセージが基準と一致するとアクションが実行されます。たとえば、アプリケーションでMessageFilters
を使用して必要なブラックリストを実装すると、指定した送信者アドレスからのすべてのメッセージを拒否できます。
MessagingFactory.createMessageFilter
を使用してメッセージ・フィルタを作成し、そのメッセージ・フィルタをMessagingClient.registerMessageFilter
を使用して登録できます。フィルタは、アプリケーションの現行フィルタ・チェーンの最後に追加されます。受信したメッセージは、フィルタ・チェーンを順に通過します。メッセージがフィルタの基準に一致すると、そのフィルタのアクションが即時に実行されます。メッセージがフィルタに一致しない場合のデフォルト・アクションでは、そのメッセージが受信されてアプリケーションに配信されます。たとえば、件名が"spam"
のメッセージを拒否するには、次のように指定します。
MessageFilter subjectFilter = MessagingFactory.createMessageFilter("spam", MessageFilter.FieldType.SUBJECT, null, MessageFilter.Action.REJECT); messagingClient.registerMessageFilter(subjectFilter);
電子メール・アドレスspammer@foo.com
からのメッセージを拒否するには、次のように指定します。
MessageFilter senderFilter = MessagingFactory.createBlacklistFilter("spammer@foo.com"); messagingClient.registerMessageFilter(senderFilter);
APIでは、クラスタ環境にクライアント・アプリケーションとUMSサーバーがデプロイされている環境をサポートしています。クラスタ化されたデプロイメントが期待どおりに機能するためには、クライアント・アプリケーションを正しく構成する必要があります。次のルールが適用されます。
2つのクライアント・アプリケーションで同じApplicationName
構成パラメータが使用されている場合、それらは同じアプリケーションのインスタンスであるとみなされます。通常、このパラメータはAPI実装によって統合されているため、アプリケーション開発者による移入は不要です。
同じアプリケーションのインスタンスでは、それらの構成のほとんどが共有され、1つのインスタンスによって登録されたAccess
ポイントやメッセージ・フィルタなどのアーティファクトは、すべてのインスタンスによって共有されます。
ApplicationInstanceName
構成パラメータを使用すると、各インスタンスを区別できます。通常、このパラメータはAPI実装によって統合されているため、アプリケーション開発者による移入は不要です。この値を移入する必要がある場合については、Javadocを参照してください。
アプリケーション・セッションは、インスタンス固有です。メッセージにセッション・フラグを設定すると、メッセージを送信したインスタンスが受信した返信を確認できます。
リスナー相関機能は、インスタンス固有です。1つのアプリケーションの2つの異なるインスタンスで複数のリスナーが登録され、異なる相関機能が提供されている場合は、インスタンスAのリスナーが起動されると相関機能Aが提供され、インスタンスBのリスナーが起動されると相関機能Bが提供されます。
クライアント・アプリケーションには、セキュアなリスナーを確立するために、1つ以上の追加構成パラメータの指定が必要な場合があります(表64-1を参照)。
通常、UMS Java APIを使用するクライアント・アプリケーションはマルチスレッド化されています。通常のシナリオにはEJBインスタンスのプールが含まれ、各シナリオではMessagingClient
インスタンスと、Webコンテナの複数のスレッドによって提供されるサーブレット・インスタンスが使用されます。UMS Java APIは、次のスレッド・モデルをサポートしています。
MessagingClientFactory.createMessagingClient
の各コールでは、新しいMessagingClient
インスタンスが戻されます。
MessagingClientFactory.createMessagingClient
と等しいパラメータ・マップを渡して作成した2つのMessagingClient
インスタンスは、同じクライアントのインスタンスです。異なるパラメータ・マップを渡して作成したインスタンスは、個別のクライアントのインスタンスです。
MessagingClient
のインスタンスは、MessagingClientFactory.createMessagingClient
を使用して取得した場合、スレッド・セーフではありません。クライアント・アプリケーションでは、所定のインスタンスが一度に1つのスレッドのみで使用されていることを確認する必要があります。この確認は、一度に1つのインスタンスのみが1つのスレッドに対して表示されていることを確認するか、MessagingClient
インスタンスに対するアクセスを同期化することで実行できます。
同じクライアントの2つのインスタンス(同じパラメータ・マップを使用して作成)は、いくつかのリソースを共有します。特に、これらのインスタンスが、メッセージとステータスのリスナーを共有し、ワーカー・スレッドの共通プールを使用して非同期メッセージング操作を実行することに注意してください。たとえば、インスタンスAがsetMessageListener()
をコールし、次にインスタンスBがsetMessageListener()
をコールした場合は、Bのリスナーがアクティブなデフォルトのメッセージ・リスナーとなります。
次に、典型的なユースケースを示します。
EJB(メッセージドリブンBeanまたはセッションBeanのいずれか)アプリケーションからUMS Java APIを使用するための推奨方法は、MessagingClient
インスタンスをBeanのejbCreate
(または同等の@PostConstruct
)メソッドに作成し、そのMessagingClient
インスタンスをBeanクラスのインスタンス変数に保存することです。EJBコンテナでは、一度に1つのスレッドのみが所定のEJBインスタンスを使用していることが確認され、これによって一度に1つのスレッドのみがBeanのMessagingClient
インスタンスにアクセスしていることが確認されます。
サーブレットからUMS Java APIを使用するには、いくつかの方法があります。通常、Webコンテナでは、サーブレット・クラスの単一のインスタンスが作成されます。このインスタンスには複数のスレッドが同時にアクセスできます。作成した単一のMessagingClient
インスタンスがサーブレット・インスタンス変数に保存されている場合、そのインスタンスへのアクセスは同期している必要があります。
他の方法は、複数のサーブレット・スレッド間で共有するMessagingClient
インスタンスのプールを作成することです。
最終的には、個別のMessagingClient
インスタンスを個別のHTTPセッションに関連付けることができます。この方法を使用すると、すべてのサーブレット・リクエストに対して単一のMessagingClient
を指定するよりも同時性が向上します。ただし、同時クライアント・リクエストが原因で複数のスレッドが1つのHTTPセッションに同時にアクセスする可能性があります。この場合は、同期がさらに必要になります。
非同期リスニングを実行するには、受信メッセージとステータス用に構成したJMSキューをリスニングする1つ以上のワーカー・スレッドを生成します。デフォルトでは、受信メッセージと受信ステータス通知に対して1つのワーカー・スレッドがそれぞれ生成されます(少なくとも1つのメッセージまたはステータス・リスナーがそれぞれ登録されていることが前提です)。クライアント・アプリケーションでは、追加のワーカー・スレッドを構成して非同期処理の同時性を向上させることができます。これを実行するには、MessagingConstants.MESSAGE_LISTENER_THREADS
キーとMessagingConstants.STATUS_LISTENER_THREAD
S
キーに整数値を指定し、これらの値をMessagingClient
インスタンスの作成時に使用した構成パラメータで、必要なワーカー・スレッドの数に設定します。
この項では、usermessagingsampleというアプリケーションの作成方法について説明します。このアプリケーションは、アウトバウンド・メッセージングおよびメッセージ・ステータスの同期取得の両方に対してUMSクライアントAPIを使用するWebクライアント・アプリケーションです。usermessagingsampleはインバウンド・メッセージングもサポートしています。デプロイして構成したusermessagingsampleを使用すると、電子メール・クライアントにメッセージを送信できます。
注意: Oracle User Messaging Serviceのコード・サンプルに関する詳細を参照したり、サンプルを自分で実行するには、Oracle SOA Suiteのサンプルを参照してください。このページにナビゲートした後は、検索条件の「UMS」を入力して「検索」をクリックすることで、Oracle User Messaging Serviceのコード・サンプルを検出できます。 |
このサンプルはWebアプリケーション・モジュール(WAR)に重点を置き、いくつかのHTMLフォームとサーブレットを定義します。Webアプリケーション・モジュールのコードと対応するXMLファイルは、提供されているusermessagingsample-src.zip
ソースから使用できます。サーブレットでは、UMSクライアントAPIを使用して、UMSクライアント・インスタンスを作成し(次に、アプリケーションの情報を登録します)、メッセージを送信します。
このアプリケーションはusermessagingsample.earというEnterprise Archive (EAR)ファイルとしてパッケージ化されており、その構造は次のとおりです。
usermessagingsample.ear
META-INF
application.xml
-- すべてのアプリケーション・モジュール用のディスクリプタ・ファイル。
weblogic-application.xml
-- oracle.sdp.messaging
共有ライブラリのimport
を含むディスクリプタ・ファイル。
usermessagingsample-web.ear
-- Webベースのフロント・エンドおよびサーブレットが格納されます。
WEB-INF
web.xml
weblogic.xml
ビルトインのサンプル・アプリケーションおよびソース・コード(usermessagingsample-src.zip)は、OTNで入手できます。
Oracle User Messaging Serviceの電子メール・ドライバを有効にしてアウトバウンド・メッセージングおよびステータスの取得を実行するには、電子メール・ドライバを次のように構成します。
OutgoingMailServer
プロパティの値として、SMTPメール・サーバーの名前を入力します。
注意: このサンプル・アプリケーションは汎用的であるため、適切なメッセージング・ドライバがデプロイされて構成されている場合は、他のチャネル経由のアウトバウンド・メッセージングもサポートできます。 |
この項では、Windowsベース・ビルドのJDeveloperを使用して、usermessagingsampleを作成、コンパイルおよびデプロイする手順を説明します。
Oracle JDeveloperで、usermessagingsample.jws
(.zipファイルに含まれています)を開きます。
Oracle JDeveloperのメイン・ウィンドウにプロジェクトが表示されます。
Webモジュールで「Oracle UMS Client」ライブラリが使用されていることを確認して、サンプル・アプリケーションのビルド依存性を満たします。
「アプリケーション・ナビゲータ」で、Webモジュール「usermessagingsample-web」を右クリックし、「プロジェクト・プロパティ」を選択します。
左側のペインで、「ライブラリとクラスパス」を選択します。
「OK」をクリックします。
usermessagingsample-webプロジェクトの下にあるJavaファイルを検索し、メッセージング・クライアントAPIを使用してメッセージの送信、ステータスの取得およびメッセージの同期受信を実行する方法を確認します。MessagingClientインスタンスは、プロジェクトのSampleUtils.java
に作成されます。
アプリケーションをデプロイする手順は、次のとおりです。
ナビゲーション・ペインでアプリケーションを右クリックし、「新規」を選択して、アプリケーション・サーバー接続を作成します。第64.11項「新規アプリケーション・サーバー接続の作成」の説明に従います。
アプリケーションをデプロイするには、「usermessagingsample application」→「デプロイ」→「usermessagingsample」→「デプロイ先」→「SOA_server」の順に選択します(図64-4)。
メッセージBuild Successful
がログに表示されていることを確認します。
メッセージDeployment Finished
がデプロイメント・ログに表示されていることを確認します。
アプリケーションが正常にデプロイされました。
サンプルを実行するには、その前に、Oracle User Messaging Serviceの追加ドライバを構成し、必要に応じて、ユーザー・メッセージング・プリファレンスでメッセージを受信するユーザー用のデフォルト・デバイスを構成する必要があります。
注意: 詳細は、『Oracle Fusion Middleware Oracle SOA SuiteおよびOracle Business Process Management Suite管理者ガイド』を参照してください。 |
Oracle WebLogic Serverの実行中のインスタンスにusermessagingsampleをデプロイした後は、次の手順を実行します。
Webブラウザを起動し、サンプル・アプリケーションのアドレスをhttp://
host
:http-port
/usermessagingsample/
と入力します。たとえば、ブラウザのナビゲーション・バーにhttp://localhost:7001/usermessagingsample/
と入力します。
プロンプトが表示された場合は、ログイン資格証明を入力します。たとえば、ユーザー名はweblogic
と入力します。メッセージ・サンプルをテストするためのブラウザ・ページが表示されます(図64-5)。
サンプル・メッセージの送信をクリックします。「メッセージの送信」ページが表示されます(図64-6)。
(オプション)送信者アドレスを次の書式で入力します。
Email:
sender_address
たとえば、Email:sender@example.com
と入力します。
受信者アドレスを1つ以上入力します。たとえば、Email:recipient@example.com
と入力します。複数のアドレスを入力する場合は、次のようにカンマ区切りリストで入力します。
Email:
recipient_address1
,
Email:
recipient_address2
ユーザー・メッセージング・プリファレンスを構成している場合、メッセージのアドレスは単にUser:
username
と指定できます。たとえば、User:weblogic
と入力します。
(オプション)件名、つまり電子メールの内容を入力します。
「送信」をクリックします。メッセージ・ステータス・ページが表示され、トランザクションの進捗が表示されます(図64-7には、メッセージング・エンジンが受信して処理するメッセージが表示されています)。
リフレッシュをクリックしてステータスを更新します。電子メール・メッセージが電子メール・サーバーに配信されると、図64-8に示すように、「ステータスの内容」フィールドに「リモート・ゲートウェイへのアウトバウンド・メッセージの配信に成功しました。」と表示されます。
この項では、usermessagingsample-echoというアプリケーションの作成方法について説明します。このアプリケーションは、UMSクライアントAPIを使用して、電子メール・アドレスからメッセージを非同期で受信し、リプライを送信者にエコーして戻すデモ・クライアント・アプリケーションです。
注意: Oracle User Messaging Serviceのコード・サンプルに関する詳細を参照したり、サンプルを自分で実行するには、Oracle SOA Suiteのサンプルを参照してください。このページにナビゲートした後は、検索条件の「UMS」を入力して「検索」をクリックすることで、Oracle User Messaging Serviceのコード・サンプルを検出できます。 |
このアプリケーションはusermessagingsample-echo.earというEnterprise Archive (EAR)ファイルとしてパッケージ化されており、その構造は次のとおりです。
usermessagingsample-echo.ear
META-INF
application.xml
-- すべてのアプリケーション・モジュール用のディスクリプタ・ファイル。
weblogic-application.xml
-- oracle.sdp.messaging
共有ライブラリのimport
を含むディスクリプタ・ファイル。
usermessagingsample-echo-web.war
-- Webベースのフロント・エンドおよびサーブレットが格納されます。受信したメッセージを処理してエコー・レスポンスを戻すリスナーも含まれています。
WEB-INF
web.xml
weblogic.xml
ビルトインのサンプル・アプリケーションおよびソース・コード(usermessagingsample-echo-src.zip
)は、OTNで入手できます。
次の各項では、usermessagingsample-echo.ear
を例にして、非同期のインバウンドおよびアウトバウンド・メッセージング機能を持つアプリケーションの作成プロセスを説明します。
Oracle User Messaging Serviceの電子メール・ドライバを有効にしてインバウンドやアウトバウンド・メッセージングおよびステータスの取得を実行するには、電子メール・ドライバを次のように構成します。
OutgoingMailServerプロパティの値として、SMTPメール・サーバーの名前を入力します。
IncomingMailServerプロパティの値として、IMAP4/POP3メール・サーバーの名前を入力します。受信ユーザー名とパスワードも構成します。
注意: このサンプル・アプリケーションは汎用的であるため、適切なメッセージング・ドライバがデプロイされて構成されている場合は、他のチャネル経由のインバウンドおよびアウトバウンド・メッセージングもサポートできます。 |
この項では、Windowsベース・ビルドのJDeveloperを使用して、usermessagingsample-echoを作成、コンパイルおよびデプロイする手順を説明します。
usermessagingsample-echo-src.zip
をJDEV_HOME
/communications/
samples/
ディレクトリに解凍します。共有ライブラリ参照をプロジェクトで有効にするには、このディレクトリを使用する必要があります。
注意: 別のディレクトリを使用する場合は、oracle.sdp.messagingライブラリ・ソース・パスをJDEV_HOME / communications/modules/oracle.sdp.messaging_11.1.1 /sdpmessaging.jar に更新する必要があります。 |
Oracle JDeveloperで、usermessagingsample-echo.jws
(.zipファイルに含まれています)を開きます(図64-9)。
Oracle JDeveloperのメイン・ウィンドウにプロジェクトが表示されます(図64-10)。
次のライブラリがusermessagingsample-echo-web
モジュールに追加されていることを確認して、サンプル・アプリケーションのビルド依存性が満たされていることを確認します。
ライブラリ: oracle.sdp.messaging、クラスパス: JDEV_HOME
/
communications/modules/oracle.sdp.messaging_11.1.1/
sdpmessaging.jar
。これはJavaライブラリで、UMS、およびUMSを使用してメッセージを送受信するアプリケーションで使用されます。
各モジュールに対して次の手順を実行します。
「アプリケーション・ナビゲータ」で、モジュールを右クリックし、「プロジェクト・プロパティ」を選択します。
左側のペインで、「ライブラリとクラスパス」を選択します(図64-11)。
「OK」をクリックします。
usermessagingsample-echo-webプロジェクトの下にあるJavaファイルを検索し、メッセージング・クライアントAPIを使用してアクセス・ポイントを登録および登録解除する方法、およびEchoListener
を使用してメッセージを非同期で受信する方法を確認します。
アプリケーションをデプロイする手順は、次のとおりです。
ナビゲーション・ペインでアプリケーションを右クリックし、「新規」を選択して、アプリケーション・サーバー接続を作成します。第64.11項「新規アプリケーション・サーバー接続の作成」の説明に従います。
アプリケーションをデプロイするには、「usermessagingsample-echo application」→「デプロイ」→「usermessagingsample-echo」→「デプロイ先」→「SOA_server」の順に選択します(図64-12)。
メッセージBuild Successful
がログに表示されていることを確認します。
メッセージDeployment Finished
がデプロイメント・ログに表示されていることを確認します。
アプリケーションが正常にデプロイされました。
サンプルを実行するには、その前に、Oracle User Messaging Serviceの追加ドライバを構成し、必要に応じて、ユーザー・メッセージング・プリファレンスでメッセージを受信するユーザー用のデフォルト・デバイスを構成する必要があります。
注意: 詳細は、『Oracle Fusion Middleware Oracle SOA SuiteおよびOracle Business Process Management Suite管理者ガイド』を参照してください。 |
Oracle WebLogic Serverの実行中のインスタンスにusermessagingsample-echoをデプロイした後は、次の手順を実行します。
Webブラウザを起動し、サンプル・アプリケーションのアドレスをhttp://
host
:
http-port
/usermessagingsample-echo/
と入力します。たとえば、ブラウザのナビゲーション・バーにhttp://localhost:7001/usermessagingsample-echo/
と入力します。
プロンプトが表示された場合は、ログイン資格証明を入力します。たとえば、ユーザー名はweblogic
と入力します。メッセージ・サンプルをテストするためのブラウザ・ページが表示されます(図64-13)。
アクセス・ポイントの登録/登録解除をクリックします。「アクセス・ポイントの登録」ページが表示されます(図64-14)。
アクセス・ポイントのアドレスを次の書式で入力します。
EMAIL:
server_address
たとえば、EMAIL:myserver@example.com
と入力します。
アクションとして登録を選択し、送信をクリックします。登録ステータス・ページが表示され、図64-15に示すように登録済と表示されます。
メッセージ・クライアント(電子メールの場合は電子メール・クライアント)から、前の手順でアクセス・ポイントとして登録したアドレスに、メッセージを送信します。
該当するチャネル用のUMSメッセージング・ドライバが正しく構成されている場合は、usermessagingsample-echoアプリケーションから戻されるエコー・メッセージを受信できるはずです。
次の手順を実行し、アプリケーション・サーバー接続を作成します。
プロジェクトを右クリックし、「新規」→「接続」→「アプリケーション・サーバー接続」の順に選択して、新規アプリケーション・サーバー接続を作成します(図64-16)。
接続にSOA_server
という名前を付けて、「次へ」をクリックします(図64-17)。
「接続タイプ」に「WebLogic 10.3」を選択します。
認証情報を入力します。ユーザー名の一般的な値はweblogic
です。
「接続」ダイアログで、SOA管理サーバーのホスト名、ポートおよびSSLポートを入力し、WLSドメインのドメイン名を入力します。
「次へ」をクリックします。
「テスト」ダイアログで、「接続のテスト」をクリックします。
メッセージSuccess!
が表示されていることを確認します。
アプリケーション・サーバー接続が作成されました。