JMS メッセージング API の使用法
インターシステムズでは、Java Message Service (JMS) によるメッセージの作成と利用に使用できる API を用意しています。コードは、クライアントを作成した後、メッセージの送信または受信のアクションを実行する、そのクライアントのメソッドを呼び出すことにより、メッセージのプロデューサまたはコンシューマとして機能します。InterSystems IRIS も、JMS のキューとトピックを作成するメソッドと削除するメソッドを提供しています。
JMS API は、他のメッセージング・プラットフォームと共有する共通のメッセージング・クラスを基本としています。このページでは、このような共通のクラスで確立されているワークフローに対し、プラットフォーム固有で発生するバリエーションについて説明します。
インターシステムズでは、ここで説明している API のほか、相互運用プロダクションの過程で JMS へのメッセージ送信と JMS からのメッセージ取得に使用できる専用のクラスを用意しています。
JMS への接続
JMS アプリケーションとの接続を作成するには以下の手順に従います。
-
設定オブジェクトを作成します。そのためには、%External.Messaging.JMSSettingsOpens in a new tab のインスタンスを作成し、必要に応じてそのプロパティを設定します。
Set settings = ##class(%External.Messaging.JMSSettings).%New() Set settings.url = "messaging.bazco.com" Set settings.connectionFactoryName = "connectionFactory" Set settings.initialContextFactoryName = "eventContextFactory" Set settings.username = "briannawaller" Set settings.password = "824yvpi"
使用できるすべてのプロパティは、"JMSSettings クラス・リファレンス" のページを参照してください。
-
メッセージング・クライアント・オブジェクトを作成します。そのためには、汎用 %External.Messaging.ClientOpens in a new tab クラスの CreateClient() メソッドを呼び出し、設定オブジェクトを 1 番目の引数として渡します。例えば以下のようにします。
Set client = ##class(%External.Messaging.Client).CreateClient(settings, .tSC) If $$$ISERR(tSC) { //handle error scenario }
このメソッドからは、参照渡しでステータス・コードが 2 番目の引数として返されます。コードでは、このステータスを確認したうえで処理を継続する必要があります。
settings オブジェクトは %External.Messaging.JMSSettingsOpens in a new tab のインスタンスなので、返されるオブジェクト (client) は %External.Messaging.JMSClientOpens in a new tab のインスタンスです。
JMS プロデューサ
InterSystems IRIS は、メッセージを作成する API メソッドを呼び出し、作成したメッセージを送信することにより、JMS アプリケーション内部でプロデューサとして機能できます。メッセージをルーティングするキューまたはトピックを作成する場合は、"キューとトピックの操作" を参照してください。以下のフローでは、クライアント・オブジェクトを使用し、プロデューサとして JMS アプリケーション を操作しています。
JMS 仕様では、指定のメッセージ・ヘッダとカスタムのメッセージ・プロパティの両方を使用して、メッセージにさまざまなメタデータを添付できます。JMS メッセージのプロパティを作成して設定するには、JMS メッセージ・プロパティ・オブジェクトの %ListOfObjectsOpens in a new tab コレクションを作成する必要があります。次のセクションで説明する JMS メッセージ・オブジェクトでは、このコレクション (一覧) をオプションのプロパティとして受け入れます。メッセージ・プロパティごとに以下を定義します。
-
%External.Messaging.JMSMessagePropertyOpens in a new tab オブジェクトの新しいインスタンスを作成します。
-
次のように、このメッセージ・プロパティ・オブジェクトのプロパティを設定します。
-
key :メッセージ・プロパティ・キー
-
type :メッセージ・プロパティ値のデータ型
-
value :メッセージ・プロパティ値の文字列表現
-
-
メッセージ・プロパティ・オブジェクトの一覧に、このメッセージ・プロパティ・オブジェクトを追加します。
メッセージ・プロパティの詳細は、JMS ドキュメントOpens in a new tabを参照してください。以下の例では、カスタムのタイム・スタンプ・プロパティを作成しています。
Set propList = ##class(%ListOfObjects).%New()
Set key = "odbcUtcTimestamp"
Set type = "String"
Set value = $zdatetime($horolog, 3, 8)
Set msgProp1 = ##class(%External.Messaging.JMSMessageProperty).%New()
Set msgProp1.key = key
Set msgProp1.type = type
Set msg.value = value
Set tSC = propList.Insert(msgProp1)
送信するメッセージを作成するには、%External.Messaging.JMSMessageOpens in a new tab オブジェクトの新しいインスタンスを作成します。つづいて、そのメッセージ・オブジェクトのプロパティを定義します。メッセージの destination の名前と type ("Text" または "Bytes") を指定する必要があります。メッセージ・タイプに応じ、textBody プロパティまたは bytesBody プロパティを使用してメッセージ本文を設定します。前のセクションの説明に従ってメッセージ・プロパティ・オブジェクトの一覧を作成している場合は、その一覧を properties プロパティとして指定します。
Set destination = "quick-start-events-queue"
Set type = "Text"
Set textBody = "MyMessage"
Set msg = ##class(%External.Messaging.JMSMessage).%New()
Set msg.destination = destination
Set msg.type = type
Set msg.textBody = textBody
Set msg.properties = propList
作成したメッセージは、JMS クライアント・オブジェクトの SendMessage() メソッドを実行することにより、送信先のキューまたはトピックに送信できます。例えば以下のようにします。
set tSC = client.SendMessage(msg)
if $$$ISERR(tSC) {
//handle error scenario
}
JMS コンシューマ
InterSystems IRIS は、トピックのメッセージを取得する API メソッドを呼び出すことにより、JMS アプリケーション内部でコンシューマとして機能できます。以下のフローでは、クライアントを使用し、コンシューマとして JMS アプリケーションを操作しています。
JMS クライアント・オブジェクトは、ReceiveMessage() メソッドを使用して JMS メッセージのコンシューマとして機能できます。このメソッドでは、JSON 形式の文字列をオプションの引数として指定することで、メッセージ取得操作の設定を指定できます。そのためには、%External.Messaging.JMSReceiveSettingsOpens in a new tab クラスの新しいインスタンスを作成し、必要に応じてそのプロパティを設定します。利用できるプロパティは以下のとおりです。
-
receiveTimeout :取得操作がタイムアウトするまでの時間 (ミリ秒) を指定する整数。設定しない場合の既定値は 100 です。
-
subscriber (オプション) :クライアントを特定するサブスクライバ名を記述した文字列
例えば以下のようにします。
Set rset = ##class(%External.Messaging.JMSReceiveSettings).%New()
Set rset.receiveTimeout = 200
メッセージを取得するには、JMS クライアント・オブジェクトが継承した ReceiveMessage() メソッドを呼び出します。このメソッドは、キューまたはトピックの名前を引数として取り、参照渡しで %ListOfObjectsOpens in a new tab としてメッセージを返します。前のセクションで説明したメッセージ取得設定を指定している場合は、設定オブジェクトの ToJSON() メソッドを使用して、その設定を 3 番目の引数として指定します。
#dim messages As %ListOfObjects
Set tSC = client.ReceiveMessage(queue, .messages, rset.ToJSON())
キューとトピックの操作
InterSystems IRIS には、JMS メッセージの送信先を管理する API が用意されています。ポイントツーポイントのメッセージングでは、キューを作成または削除できます。パブリッシャツーパブリッシャのメッセージングでは、トピックを作成または削除できます。
キューの作成または削除
JMS クライアント・オブジェクトは、キューを作成するための CreateQueue() メソッドを備えています。CreateQueue() は、キューの名前を引数として受け入れます。
Set queueName = "quick-start-events"
Set tSC = client.CreateQueue(queueName)
また、すべてのメッセージング・プラットフォームに共通のメソッドを使用して、キューを作成することもできます。詳細は、"%External.Messaging.Client.CreateQueueOrTopic()Opens in a new tab" を参照してください。
この API でサポートされているすべてのメッセージング・プラットフォームのクライアント・オブジェクトに共通のメソッドを使用して、JMS キューを削除できます。詳細は、"%External.Messaging.Client.DeleteQueueOrTopic()Opens in a new tab" を参照してください。
Set tSC = client.DeleteQueueOrTopic(queueName)
トピックの作成または削除
JMS クライアント・オブジェクトは、トピックを作成するための CreateTopic() メソッドを備えています。CreateTopic() は、トピックの名前を引数として受け入れます。
Set topicName = "alerts_urgent"
Set tSC = client.CreateTopic(topicName)
また、すべてのメッセージング・プラットフォームに共通のメソッドを使用してトピックを作成することもできます。詳細は、"%External.Messaging.Client.CreateQueueOrTopic()Opens in a new tab" を参照してください。
この API でサポートされているすべてのメッセージング・プラットフォームのクライアント・オブジェクトに共通のメソッドを使用して、JMS トピックを削除できます。詳細は、"%External.Messaging.Client.DeleteQueueOrTopic()Opens in a new tab" を参照してください。
Set tSC = client.DeleteQueueOrTopic(topicName)
クライアントの終了
JMS アプリケーションとの通信を完了した InterSystems IRIS アプリケーションは、クライアント・オブジェクトの Close() メソッドを使用してクライアントを閉じる必要があります。例えば以下のようにします。
Do:client'="" client.Close()