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 オブジェクトの新しいインスタンスを作成します。
-
次のように、このメッセージ・プロパティ・オブジェクトのプロパティを設定します。
-
メッセージ・プロパティ・オブジェクトの一覧に、このメッセージ・プロパティ・オブジェクトを追加します。
メッセージ・プロパティの詳細は、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() メソッドを呼び出します。このメソッドは、キューまたはトピックの名前を引数として取り、参照渡しで %ListOfObjectsOpens in a new tab としてメッセージを返します。前のセクションで説明したメッセージ取得設定を指定している場合は、設定オブジェクトの ToJSON() メソッドを使用して、その設定を 3 番目の引数として指定します。
#dim messages As %ListOfObjects
Set tSC = client.ReceiveMessage(queue, .messages, rset.ToJSON())
クライアントの終了
JMS アプリケーションとの通信を完了した InterSystems IRIS アプリケーションは、クライアント・オブジェクトの Close() メソッドを使用してクライアントを閉じる必要があります。例えば以下のようにします。
Do:client'="" client.Close()
