第 3 章   イベント通知サービス Java (JMS) API リファレンス


この章では、ENS における Java (JMS) API の実装および Java API 自体について説明します。

この章は、次の節で構成されています。

• イベント通知サービス Java (JMS) API の実装

• Java (JMS) API の概要

• 実装上の注意

イベント通知サービス Java (JMS) API の実装

---

ENS Java API は、iPlanet Messaging Server 5.2 および iPlanet Calendar Server 5.1 に含まれています。 Java API は、Java Message Service 仕様 (JMS) に準拠しています。

ENS は、Java Message Service に対するプロバイダの役割を果たします。 このため、JMS は ENS に Java API を提供します。ソフトウェアは、ベースライブラリとデモプログラムで構成されています。

Java API を使用するための前提条件

Java API を使用するには、ENS を使用できるようにしておく必要があります。 iPlanet Messaging Server で ENS を使用可能にする方法については、『iPlanet Messaging Server 5.2 管理者ガイド』の付録 C を参照してください。 iPlanet Calendar Server では、デフォルトで ENS が使用できます。

さらに、次のソフトウェアもインストールする必要があります。このソフトウェアは、iPlanet Messaging Server も iPlanet Calendar Server もどちらも提供していません。

• Java Development Kit (JDK) 1.2 以降

• Java Message Service 1.0.2a 以降 (1.0.2a でテスト済み)

このソフトウェアは、http://java.sun.com からダウンロードできます。

サンプル Java プログラム

iPlanet Messaging Server 5.2 サンプルプログラムの JmsSample および JBiff は、server-root/bin/msg/enssdk/java/com/iplanet/ens/samples ディレクトリに格納されています。 JmsSample は、汎用 ENS サンプルプログラムです。 JBiff は、iPlanet Messaging Server 固有のサンプルプログラムです。

JBiff の場合、次の追加項目が必要となります。

• Java Mail jar ファイル (JavaMail 1.2 でテスト済み)

• Java Activation Framework (JavaMail に必要、JAF1.0.1 でテスト済み)

上記は、http://java.sun.com からダウンロードできます。

環境を設定する

この節では、サンプルプログラムをコンパイルして実行できるようにするために必要となることがらについて説明します。

JmsSample プログラムをコンパイルするには

1. CLASSPATH が次の項目を含むよう設定します。

   ens.jar ファイル - ens.jar

   (iPlanet Messaging Server では、ens.jar は、server-root/java/jars/ ディレクトリにあります。)

   Java Message Service - full-path/jms1.0.2/jms.jar

2. server-root/bin/msg/enssdk/java ディレクトリに移ります。

3. 次のコマンドを実行します。

javac com/iplanet/ens/samples/JmsSample.java

JBiff プログラムをコンパイルするには

1. CLASSPATH が次の項目を含むよう設定します。

   ens.jar ファイル - ens.jar

   (iPlanet Messaging Server では、ens.jar は、server-root/java/jars/ ディレクトリにあります。)

   Java Message Service - full-path/jms1.0.2/jms.jar

   JavaMail - full-path/javamail-1.2/mail.jar

   Java Activation Framework - full-path/jaf-1.0.1/activation.jar

2. server-root/bin/msg/enssdk/java ディレクトリに移ります。

3. 次のコマンドを実行します。

javac com/iplanet/ens/samples/JBiff.java

JmsSample プログラムを実行するには

1. server-root/bin/msg/enssdk/java ディレクトリに移ります。

2. 次のコマンドを実行します。

java com.iplanet.ens.samples.JmsSample

3. 次の 3 つの項目の入力が要求されます。
   • ENS イベント参照 ( iPlanet Messaging Server の場合の例: enp://127.0.0.1/store)

   • ENS ホスト名

   • ENS ポート (通常は 7997)

4. イベントを公開します。

   iPlanet Messaging Server には、イベントを公開する次の 2 つの方法があります。

   • ENS の apub C サンプルプログラムが使用できます。 詳細については、「iPlanet Messaging Server のコーディング例」 を参照してください。

   • ENS が使用可能である場合は、iBiff が iPlanet Messaging Server 関連のイベントを公開するよう設定します。

   iPlanet Calendar Server の場合、イベントはカレンダーサーバによって公開されます。

JBiff デモプログラムを実行するには

前提条件: JBiff デモプログラムを実行するには、iPlanet Messaging Server で ENS を使用できるようにしておく必要があります。 ENS を使用可能にする手順については、『iPlanet Messaging Server 5.2 管理者ガイド 』の付録 C を参照してください。

---

注	デモは現在、ENS イベント参照 enp://127.0.0.1/store を使用するようハードコード化されています。 これは、iBiff 通知プラグインが使用するデフォルトのイベント参照です。

---

1. server-root/bin/msg/enssdk/java ディレクトリに移ります。

2. 次のコマンドを実行します。

java com.iplanet.ens.samples.JBiff

3. ユーザ ID (userid)、ホスト名 (hostname)、およびパスワード (password) の入力を求められます。

   コードは、ENS サーバおよび IMAP サーバが hostname 上で実行していることを前提としています。 userid および password は、IMAP アカウントにアクセスするための IMAP ユーザ名およびパスワードです。

2 つのテストプログラムは、ENS サブスクライバです。 電子メールメッセージが iPlanet Messaging Server を介して転送されると、iBiff からイベントを受信します。 または、apub C サンプルプログラムを使用して、イベントを生成することもできます。 詳細については、「iPlanet Messaging Server のコーディング例」 を参照してください。

Java (JMS) API の概要

---

Java API for ENS は、標準 Java Messaging Service (JMS) API のサブセットを使用し、次の 2 つの新しい固有メソッドが加わっています。

• com.iplanet.ens.jms.EnsTopicConnFactory

• com.iplanet.ens.jms.EnsTopic

JMS では、2 つの ENS 固有クラスが提供する TopicConnectionFactory および Topic の作成が必要です。

標準 JMS のクラスとメソッドの詳細については、次のサイトにある JMS マニュアルを参照してください。

http://java.sun.com/products/jms/docs.html

新しい固有メソッド

2 つの固有メソッドクラスとは、EnsTopicConnFactory および EnsTopic です。

com.iplanet.ens.jms.EnsTopicConnFactory

メソッドについて
このメソッドは、javax.jms.TopicConnectionFactory を返すコンストラクタです。 JNDI 形式の検索を使用して TopicConnectionFactory オブジェクトを取得する代わりに、このメソッドが提供されます。

構文
public EnsTopicConnFactory (String name,
String hostname,
int port
OutputStream logStream)

throws java.io.IOException

引数

表 3-1 EnsTopicConnFactory の引数

引数	型	説明
name	String	javax.jms.Connection のクライアント ID
hostname	String	ENS サーバのホスト名
port	int	ENS サーバの TCP ポート
logStream	OutputStream	メッセージが記録される場所 (NULL は指定できません)

com.iplanet.ens.jms.EnsTopic

このメソッドについて
このメソッドは、javax.jms.Topic を返すコンストラクタです。 JNDI 形式の検索を使用して javax.jms.Topic オブジェクトを取得する代わりに、このメソッドが提供されます。

構文
public EnsTopic (String eventRef)

引数

表 3-2 EnsTopic の引数

引数	型	説明
eventRef	String	ENS イベント参照

実装上の注意

---

この節では、ENS Java API を実装するときに理解しておくべき項目について説明します。

現在の実装における欠点

Java API の現在の実装では、初期プロバイダインタフェースが提供されません。

JMS Topic Connection Factory および ENS Destination が明示的に呼び出されます。 これらは、com.iplanet.ens.jms.EnsTopicConnFactory および com.iplanet.ens.jms.EnsTopic です。ENS では、TopicConnectionFactory オブジェクトや Topic オブジェクトの取得に JNDI は使用しません。

通知の配信

通知は、javax.jms.TextMessage として配信されます。 ENS イベント参照のパラメータとその値は TextMessage に対するプロパティ名として提供されます。 ペイロードは、TextMessage のデータとして提供されます。

JMS ヘッダー

• JMSDeliveryMode は常に、NON_PERSISTENT に設定されています (つまり以降の配信のためにメッセージは格納されません)。

• JMSRedelivered は常に、false に設定されています。

• JMSMessageID は、内部 ID に設定されています。つまり、iPlanet Messaging Server の電子メールメッセージのヘッダーの SMTP MessageID には設定されていません。

• ペイロードは常に、javax.jms.TextMessage です。 ENS のペイロードに対応しています。

• JMSDestination は、完全イベント参照に設定されています (つまり、この通知に固有のパラメータ/値を含んでいます)。

• JMSCorrelationID - 内部シーケンス番号に設定されます。

• JMSTimestamp - メッセージが送信された時刻に設定されます。
  • iPlanet Messaging Server および iBiff の場合、timestamp パラメータに相当します。

  • iPlanet Calendar Server では、未使用です。

• JMSType - 通知の種類。
  • iPlanet Messaging Server および iBiff では、evtType パラメータに相当します。

  • iPlanet Calendar Server では、未使用です。

• 追加のプロパティ:
  • イベント参照の各パラメータと値は、ヘッダーではプロパティになります。 すべてのプロパティ値は、String 型です。

• 未使用ヘッダーは、JMSExpiration、JMSpriority、JMSReplyTo です。

その他

• MessageSelectors は実装されていません。

• JMS は、永続的サブスクライバおよび非永続的サブスクライバという概念を使用しています。 永続的サブスクライバは、オフライン、または破壊的な問題が発生した場合でも、サブスクライバに通知が送信されることを保証する機能です。破壊的な問題とは、ENS サーバがパブリッシャから通知を受け取ったが、サブスクライバへの配信を行う前にダウンした、というような状況です。
  • 非永続的サブスクライバは実装されています。

  • また、永続的サブスクライバを使用することもできますが、永続的サブスクライバとしての完全な機能は実装されていません。

  • サブスクライバがメッセージを受信して初めてパブリッシャがアクノリッジされるという点で、永続的サブスクライバは実装されています。

  • メッセージが持続的ではなく、オフラインサブスクライバに対しては (オンラインになった後も) 配信が行われない という点で、永続的サブスクライバは実装されていません。 特に、JMSRedelivered は常に false に設定されています。