パッケージ jakarta.jms

インターフェース MessageProducer

すべてのスーパーインターフェース:
AutoCloseableSE
すべての既知のサブインターフェース:
QueueSender, TopicPublisher
public interface MessageProducer extends AutoCloseableSE
クライアントは MessageProducer オブジェクトを使用して宛先にメッセージを送信します。MessageProducer オブジェクトは、Destination オブジェクトを、セッションによって提供されるメッセージプロデューサー作成メソッドに渡すことによって作成されます。

MessageProducer は、すべてのメッセージプロデューサーの親インターフェースです。

クライアントには、宛先を指定せずにメッセージプロデューサーを作成するオプションもあります。この場合、送信操作ごとに宛先を指定する必要があります。この種のメッセージプロデューサーの一般的な用途は、リクエストの JMSReplyTo 宛先を使用してリクエストに返信を送信することです。

クライアントは、メッセージプロデューサーが送信するメッセージのデフォルトの配信モード、優先度、存続時間、配信遅延を指定できます。個々のメッセージの配信モード、優先度、存続時間も指定できます。

クライアントは、送信する各メッセージの存続時間をミリ秒単位で指定できます。この値は、メッセージの有効期間と送信時の GMT の合計であるメッセージの有効期限を定義します（トランザクション送信の場合、これはクライアントがメッセージを送信する時間であり、トランザクションがコミットされる時間ではありません）。

Jakarta Messaging プロバイダーは、メッセージを正確に期限切れにするために最善を尽くす必要があります。ただし、Jakarta Messaging API は提供される精度を定義しません。

導入:
JMS 1.0
バージョン:
Jakarta Messaging 2.0
関連事項:

  • メソッドのサマリー

    修飾子と型
    メソッド
    説明
    void
    close()
    メッセージプロデューサーを閉じます。
    long
    getDeliveryDelay()
    メッセージが送信されてから Jakarta Messaging プロバイダーがメッセージをコンシューマーに配信するまでに経過する必要がある最小時間をミリ秒単位で取得します。
    int
    getDeliveryMode()
    プロデューサーのデフォルトの配信モードを取得します。
    Destination
    getDestination()
    この MessageProducer に関連付けられた宛先を取得します。
    boolean
    getDisableMessageID()
    メッセージ ID が無効になっているかどうかの指標を取得します。
    boolean
    getDisableMessageTimestamp()
    メッセージのタイムスタンプが無効になっているかどうかの指標を取得します。
    int
    getPriority()
    プロデューサーのデフォルトの優先度を取得します。
    long
    getTimeToLive()
    生成されたメッセージがメッセージシステムによって保持される必要があるディスパッチ時間から、ミリ秒単位のデフォルトの時間を取得します。
    void
    send(Destination destination, Message message)
    MessageProducer のデフォルトの配信モード、優先度、存続時間を使用して、身元不明のメッセージプロデューサーの宛先にメッセージを送信します。
    void
    send(Destination destination, Message message, int deliveryMode, int priority, long timeToLive)
    配信モード、優先度、有効期間を指定して、身元不明のメッセージプロデューサーの宛先にメッセージを送信します。
    void
    send(Destination destination, Message message, int deliveryMode, int priority, long timeToLive, CompletionListener completionListener)
    不明なメッセージプロデューサーの宛先にメッセージを送信し、配信モード、優先度、存続時間を指定し、別のスレッドでメッセージの送信に関連する作業の一部を実行し、指定された CompletionListener に通知する操作が完了しました。
    void
    send(Destination destination, Message message, CompletionListener completionListener)
    MessageProducer のデフォルトの配信モード、優先度、存続時間を使用して、メッセージを特定されていないメッセージプロデューサーの宛先に送信し、別のスレッドでメッセージを送信し、指定された CompletionListener に通知する作業の一部を実行します操作が完了したとき。
    void
    send(Message message)
    MessageProducer のデフォルトの配信モード、優先度、存続時間を使用してメッセージを送信します。
    void
    send(Message message, int deliveryMode, int priority, long timeToLive)
    配信モード、優先度、存続時間を指定して、メッセージを送信します。
    void
    send(Message message, int deliveryMode, int priority, long timeToLive, CompletionListener completionListener)
    メッセージを送信し、配信モード、優先度、存続時間を指定し、別のスレッドでのメッセージの送信に関連する作業の一部を実行し、操作の完了時に指定された CompletionListener に通知します。
    void
    send(Message message, CompletionListener completionListener)
    MessageProducer のデフォルトの配信モード、優先度、存続時間を使用してメッセージを送信し、別のスレッドでのメッセージの送信に関連する作業の一部を実行し、操作が完了したときに指定の CompletionListener に通知します。
    void
    setDeliveryDelay(long deliveryDelay)
    メッセージが送信されてから Jakarta Messaging プロバイダーがメッセージをコンシューマーに配信するまでに経過する必要がある最小時間をミリ秒単位で設定します。
    void
    setDeliveryMode(int deliveryMode)
    プロデューサーのデフォルトの配信モードを設定します。
    void
    setDisableMessageID(boolean value)
    メッセージ ID を無効にするかどうかを指定します。
    void
    setDisableMessageTimestamp(boolean value)
    メッセージのタイムスタンプを無効にするかどうかを指定します。
    void
    setPriority(int defaultPriority)
    プロデューサーのデフォルトの優先度を設定します。
    void
    setTimeToLive(long timeToLive)
    生成されたメッセージがメッセージシステムによって保持される、ディスパッチ時間からのデフォルトの時間をミリ秒単位で設定します。

  • メソッドの詳細

    • setDisableMessageID

      void setDisableMessageID(boolean value) throws JMSException
      メッセージ ID を無効にするかどうかを指定します。

      メッセージ ID はメッセージのサイズを作成して拡大するために多少の労力を費やすため、一部の Jakarta Messaging プロバイダーは、メッセージ ID がアプリケーションによって使用されていないというヒントが与えられた場合、メッセージのオーバーヘッドを最適化できる場合があります。このメソッドを呼び出すことにより、Jakarta Messaging アプリケーションは、この MessageProducer を使用して送信されるすべてのメッセージに対して、この潜在的な最適化を可能にします。Jakarta Messaging プロバイダーがこのヒントを受け入れる場合、これらのメッセージのメッセージ ID を null に設定する必要があります。プロバイダーがヒントを無視する場合は、メッセージ ID を通常の一意の値に設定する必要があります。

      メッセージ ID はデフォルトで有効になっています。

      パラメーター:
      value - メッセージ ID を無効にできるかどうかを示します
      例外:
      JMSException - 内部エラーのために Jakarta Messaging プロバイダーがメッセージ ID を無効に設定できない場合。

    • getDisableMessageID

      boolean getDisableMessageID() throws JMSException
      メッセージ ID が無効になっているかどうかの指標を取得します。
      戻り値:
      メッセージ ID が無効になっているかどうかの指標
      例外:
      JMSException - Jakarta Messaging プロバイダーが、内部エラーのためにメッセージ ID が無効になっているかどうかを判断できない場合。

    • setDisableMessageTimestamp

      void setDisableMessageTimestamp(boolean value) throws JMSException
      メッセージのタイムスタンプを無効にするかどうかを指定します。

      タイムスタンプはメッセージのサイズを作成および増加するために多少の労力を要するため、一部の Jakarta Messaging プロバイダーは、アプリケーションでタイムスタンプが使用されていないというヒントが与えられた場合、メッセージのオーバーヘッドを最適化できる場合があります。このメソッドを呼び出すことにより、Jakarta Messaging アプリケーションは、この MessageProducer を使用して送信されるすべてのメッセージに対して、この潜在的な最適化を可能にします。Jakarta Messaging プロバイダーがこのヒントを受け入れる場合、これらのメッセージのタイムスタンプはゼロに設定する必要があります。プロバイダーがヒントを無視する場合、タイムスタンプを通常の値に設定する必要があります。

      メッセージのタイムスタンプはデフォルトで有効になっています。

      パラメーター:
      value - メッセージのタイムスタンプを無効にできるかどうかを示します
      例外:
      JMSException - 内部エラーのために Jakarta Messaging プロバイダーがタイムスタンプを無効に設定できない場合。

    • getDisableMessageTimestamp

      boolean getDisableMessageTimestamp() throws JMSException
      メッセージのタイムスタンプが無効になっているかどうかの指標を取得します。
      戻り値:
      メッセージのタイムスタンプが無効になっているかどうかの指標
      例外:
      JMSException - Jakarta Messaging プロバイダーが、内部エラーのためにタイムスタンプが無効になっているかどうかを判断できない場合。

    • setDeliveryMode

      void setDeliveryMode(int deliveryMode) throws JMSException
      プロデューサーのデフォルトの配信モードを設定します。

      配信モードはデフォルトで PERSISTENT に設定されています。

      パラメーター:
      deliveryMode - このメッセージプロデューサーのメッセージ配信モード。有効な値は DeliveryMode.NON_PERSISTENT および DeliveryMode.PERSISTENT です
      例外:
      JMSException - 内部エラーのために Jakarta Messaging プロバイダーが配信モードの設定に失敗した場合。
      関連事項:

    • getDeliveryMode

      int getDeliveryMode() throws JMSException
      プロデューサーのデフォルトの配信モードを取得します。
      戻り値:
      このメッセージプロデューサーのメッセージ配信モード
      例外:
      JMSException - 内部エラーが原因で Jakarta Messaging プロバイダーが配信モードを取得できなかった場合
      関連事項:

    • setPriority

      void setPriority(int defaultPriority) throws JMSException
      プロデューサーのデフォルトの優先度を設定します。

      Jakarta Messaging API は 10 レベルの優先度値を定義し、0 が最低優先度、9 が最高優先度です。クライアントは、優先度 0 〜 4 を通常の優先度のグラデーションと見なし、優先度 5 〜 9 を優先度の優先度のグラデーションと見なす必要があります。優先度はデフォルトで 4 に設定されています。

      パラメーター:
      defaultPriority - このメッセージプロデューサーのメッセージ優先度。0 から 9 までの値でなければなりません
      例外:
      JMSException - 内部エラーが原因で Jakarta Messaging プロバイダーが優先度の設定に失敗した場合
      関連事項:

    • getPriority

      int getPriority() throws JMSException
      プロデューサーのデフォルトの優先度を取得します。
      戻り値:
      このメッセージプロデューサーのメッセージ優先度
      例外:
      JMSException - 内部エラーが原因で Jakarta Messaging プロバイダーが優先度を取得できなかった場合。
      関連事項:

    • setTimeToLive

      void setTimeToLive(long timeToLive) throws JMSException
      生成されたメッセージがメッセージシステムによって保持される、ディスパッチ時間からのデフォルトの時間をミリ秒単位で設定します。

      存続時間はデフォルトでゼロに設定されています。

      パラメーター:
      timeToLive - メッセージの存続時間（ミリ秒）。ゼロは無制限
      例外:
      JMSException - 内部エラーのために Jakarta Messaging プロバイダーが存続時間を設定できない場合。
      関連事項:

    • getTimeToLive

      long getTimeToLive() throws JMSException
      生成されたメッセージがメッセージシステムによって保持される必要があるディスパッチ時間から、ミリ秒単位のデフォルトの時間を取得します。
      戻り値:
      メッセージの存続時間（ミリ秒）。ゼロは無制限
      例外:
      JMSException - 内部エラーのために Jakarta Messaging プロバイダーが存続時間を取得できない場合。
      関連事項:

    • setDeliveryDelay

      void setDeliveryDelay(long deliveryDelay) throws JMSException
      メッセージが送信されてから Jakarta Messaging プロバイダーがメッセージをコンシューマーに配信するまでに経過する必要がある最小時間をミリ秒単位で設定します。

      トランザクション送信の場合、この時間は、トランザクションがコミットされたときではなく、クライアントがメッセージを送信したときに始まります。

      deliveryDelay はデフォルトでゼロに設定されています。

      パラメーター:
      deliveryDelay - ミリ秒単位の配信遅延。
      例外:
      JMSException - Jakarta Messaging プロバイダーが内部エラーのために配信遅延の設定に失敗した場合
      導入:
      JMS 2.0
      関連事項:

    • getDeliveryDelay

      long getDeliveryDelay() throws JMSException
      メッセージが送信されてから Jakarta Messaging プロバイダーがメッセージをコンシューマーに配信するまでに経過する必要がある最小時間をミリ秒単位で取得します。
      戻り値:
      ミリ秒単位の配信遅延。
      例外:
      JMSException - 内部エラーのために Jakarta Messaging プロバイダーが配信遅延を取得できない場合。
      導入:
      JMS 2.0
      関連事項:

    • getDestination

      Destination getDestination() throws JMSException
      この MessageProducer に関連付けられた宛先を取得します。
      戻り値:
      このプロデューサーの Destination
      例外:
      JMSException - 内部エラーのために Jakarta Messaging プロバイダーがこの MessageProducer の宛先の取得に失敗した場合
      導入:
      JMS 1.1

    • close

      void close() throws JMSException
      メッセージプロデューサーを閉じます。

      プロバイダーは、Java 仮想マシンの外部で MessageProducer に代わって一部のリソースを割り当てる可能性があるため、クライアントは、必要のないときに閉じる必要があります。最終的にこれらのリソースを再利用するためにガベージコレクションに依存することは、十分なタイムリーではない可能性があります。

      このメソッドは、この MessageProducer の不完全な非同期送信操作が完了し、 CompletionListener コールバックが返されるまで返さないでください。エラーが発生しない限り、不完全な送信は正常に完了することが許可されている必要があります。

      CompletionListener コールバックメソッドはそれ自体の MessageProducer で close を呼び出さないでください。これを行うと、 IllegalStateException がスローされます。

      次で指定:
      インターフェース AutoCloseableSE の close 
      例外:
      IllegalStateException - このメソッドは、独自の MessageProducer で CompletionListener コールバックメソッドによって呼び出されました。
      JMSException - 内部エラーが原因で Jakarta Messaging プロバイダーがプロデューサーを閉じることができない場合。

    • send

      void send(Message message) throws JMSException
      MessageProducer のデフォルトの配信モード、優先度、存続時間を使用してメッセージを送信します。
      パラメーター:
      message - 送信するメッセージ
      例外:
      JMSException - 内部エラーのために Jakarta Messaging プロバイダーがメッセージの送信に失敗した場合。
      MessageFormatException - 無効なメッセージが指定された場合。
      InvalidDestinationException - クライアントが無効な宛先を持つ MessageProducer でこのメソッドを使用する場合。
      UnsupportedOperationExceptionSE - クライアントが、作成時に宛先を指定しなかった MessageProducer でこのメソッドを使用する場合。
      導入:
      JMS 1.1
      関連事項:

    • send

      void send(Message message, int deliveryMode, int priority, long timeToLive) throws JMSException
      配信モード、優先度、存続時間を指定して、メッセージを送信します。
      パラメーター:
      message - 送信するメッセージ
      deliveryMode - 使用する配信モード
      priority - このメッセージの優先度
      timeToLive - メッセージの存続期間 (ミリ秒単位)
      例外:
      JMSException - 内部エラーのために Jakarta Messaging プロバイダーがメッセージの送信に失敗した場合。
      MessageFormatException - 無効なメッセージが指定された場合。
      InvalidDestinationException - クライアントが無効な宛先を持つ MessageProducer でこのメソッドを使用する場合。
      UnsupportedOperationExceptionSE - クライアントが、作成時に宛先を指定しなかった MessageProducer でこのメソッドを使用する場合。
      導入:
      JMS 1.1
      関連事項:

    • send

      void send(Destination destination, Message message) throws JMSException
      MessageProducer のデフォルトの配信モード、優先度、存続時間を使用して、身元不明のメッセージプロデューサーの宛先にメッセージを送信します。

      通常、メッセージプロデューサーには作成時に宛先が割り当てられます。ただし、Jakarta Messaging API は、未確認のメッセージプロデューサーもサポートしているため、メッセージが送信されるたびに宛先を指定する必要があります。

      パラメーター:
      destination - このメッセージの送信先
      message - 送信するメッセージ
      例外:
      JMSException - 内部エラーのために Jakarta Messaging プロバイダーがメッセージの送信に失敗した場合。
      MessageFormatException - 無効なメッセージが指定された場合。
      InvalidDestinationException - クライアントが無効な宛先でこのメソッドを使用する場合。
      UnsupportedOperationExceptionSE - クライアントが作成時に宛先を指定した MessageProducer でこのメソッドを使用する場合。
      導入:
      JMS 1.1
      関連事項:

    • send

      void send(Destination destination, Message message, int deliveryMode, int priority, long timeToLive) throws JMSException
      配信モード、優先度、有効期間を指定して、身元不明のメッセージプロデューサーの宛先にメッセージを送信します。

      通常、メッセージプロデューサーには作成時に宛先が割り当てられます。ただし、Jakarta Messaging API は、未確認のメッセージプロデューサーもサポートしているため、メッセージが送信されるたびに宛先を指定する必要があります。

      パラメーター:
      destination - このメッセージの送信先
      message - 送信するメッセージ
      deliveryMode - 使用する配信モード
      priority - このメッセージの優先度
      timeToLive - メッセージの存続期間 (ミリ秒単位)
      例外:
      JMSException - 内部エラーのために Jakarta Messaging プロバイダーがメッセージの送信に失敗した場合。
      MessageFormatException - 無効なメッセージが指定された場合。
      InvalidDestinationException - クライアントが無効な宛先でこのメソッドを使用する場合。
      UnsupportedOperationExceptionSE - クライアントが作成時に宛先を指定した MessageProducer でこのメソッドを使用する場合。
      導入:
      JMS 1.1
      関連事項:

    • send

      void send(Message message, CompletionListener completionListener) throws JMSException
      MessageProducer のデフォルトの配信モード、優先度、存続時間を使用してメッセージを送信し、別のスレッドでメッセージを送信する作業の一部を実行し、操作が完了したときに指定された CompletionListener に通知します。Jakarta Messaging は、これを「非同期送信」と呼びます。

      メッセージが正常に送信されると、Jakarta Messaging プロバイダーは、アプリケーションが指定した CompletionListener オブジェクトでコールバックメソッド onCompletion を呼び出します。そのコールバックが呼び出された場合のみ、アプリケーションは、通常の同期送信が実行された場合と同じ程度の信頼性でメッセージが正常に送信されたことを確認できます。この程度の信頼性を必要とするアプリケーションは、続行する前にコールバックが呼び出されるまで待機する必要があります。

      次の情報は、非同期送信が通常どのように実装されるかを示すことを目的としています。

      一部の Jakarta Messaging プロバイダーでは、通常の同期送信では、メッセージを リモート Jakarta Messaging サーバーに送信し、確認応答の受信を待ってから戻ります。このようなプロバイダーは、メッセージを リモート Jakarta Messaging サーバーに送信し、確認応答を待たずに戻ることで、非同期送信を実装することが期待されます。確認応答を受信すると、Jakarta Messaging プロバイダーは、アプリケーション指定の CompletionListener オブジェクトの onCompletion メソッドを呼び出してアプリケーションに通知します。何らかの理由で確認応答が受信されない場合は、Jakarta Messaging プロバイダーは CompletionListener の onException メソッドを呼び出してアプリケーションに通知します。

      Jakarta Messaging 仕様で許容される信頼性のレベルが低い場合、通常の同期送信では確認応答を待たないことがあります。その場合、非同期送信は同期送信と同様になることが予想されます。つまり、Jakarta Messaging プロバイダーはメッセージを リモート Jakarta Messaging サーバーに送信し、確認応答を待たずに戻ります。ただし、Jakarta Messaging プロバイダーは、アプリケーション指定の CompletionListener オブジェクトで onCompletion メソッドを呼び出すことにより、送信が完了したことをアプリケーションに通知します。

      以下に示す要件を満たしている限り、呼び出し元のスレッドで何を実行し、非同期で何を実行するかを正確に決定するのは Jakarta Messaging プロバイダーの責任です。

      サービス品質 : 送信操作が正常に完了した後、つまり通常の同期送信が実行された場合と同じ信頼度でメッセージが正常に送信された後、JMS プロバイダーは CompletionListener の onCompletion メソッドを呼び出す必要があります。これより前に CompletionListener を呼び出してはなりません。

      例外 : send メソッドの呼び出し中に例外が発生した場合は、send メソッドを呼び出しているスレッドで適切な例外がスローされる必要があります。この場合、Jakarta Messaging プロバイダーは CompletionListener の onCompletion または onException メソッドを呼び出してはなりません。send メソッドを呼び出しているスレッドでスローできない例外が発生した場合は、Jakarta Messaging プロバイダーは CompletionListener の onException メソッドを呼び出す必要があります。どちらの場合も、例外が発生した場合、メッセージが正常に送信されたかどうかは未定義です。

      メッセージの順序 : 同じ MessageProducer を使用して複数のメッセージを送信する場合は、Jakarta Messaging メッセージの順序の要件を満たす必要があります。これは、同期送信と非同期送信の組み合わせが実行された場合でも適用されます。アプリケーションは、次のメッセージを送信する前に非同期送信が完了するのを待つ必要はありません。

      クローズ、コミット、ロールバック : MessageProducer またはそのセッションまたは接続で close メソッドが呼び出された場合、Jakarta Messaging プロバイダーは、オブジェクトを閉じて戻る前に、不完全な送信操作が完了し、すべての CompletionListener コールバックが戻るまでブロックする必要があります。セッションがトランザクションされる（ローカルトランザクションを使用する）場合、セッションのコミットまたはロールバックメソッドが呼び出されると、Jakarta Messaging プロバイダーは、不完全な送信操作が完了し、コミットまたはロールバックを実行する前にすべての CompletionListener コールバックが返されるまでブロックする必要があります。エラーが発生しない限り、不完全な送信は正常に完了することが許可されている必要があります。

      CompletionListener コールバックメソッドはそれ自体の接続、セッションまたは MessageProducer close を呼び出さないでください > または、独自のセッションで commit または rollback を呼び出します。これを行うと、 close 、 commit 、または rollback が IllegalStateException をスローします。

      Jakarta EE での使用に関する制限このメソッドは、Jakarta EE EJB または Web コンテナーでは使用しないでください。これを行うと、JMSException がスローされる可能性がありますが、これは保証されていません。

      メッセージヘッダー Jakarta Messaging は、" 送信時の Jakarta Messaging プロバイダー " によって設定する必要がある、多数のメッセージヘッダーフィールドとメッセージプロパティを定義します。送信が非同期の場合、これらのフィールドとプロパティは、CompletionListener が呼び出された後にのみ、送信クライアントでアクセスできます。CompletionListener の onException メソッドが呼び出されると、これらのメッセージヘッダーフィールドとプロパティの状態は未定義になります。

      スレッドの制限 : 非同期送信を実行するアプリケーションは、JMS で定義されているスレッド制限を確認する必要があります。これは、セッションが一度に 1 つのスレッドのみによって使用される可能性があることを意味します。

      CompletionListener を設定しても、セッションは CompletionListener を呼び出す制御スレッド専用にはなりません。アプリケーションスレッドは、非同期送信を実行した後もセッションを引き続き使用できます。ただし、アプリケーションスレッドが同時にセッションを使用している可能性がある場合は、 CompletionListener のコールバックメソッドでセッションを使用しないでください。

      Jakarta Messaging プロバイダーによる CompletionListener の使用 : セッションは、一度に 1 つの CompletionListener コールバックメソッドのみを呼び出します。特定の MessageProducer について、コールバック（onCompletion と onException の両方）は、非同期送信メソッドへの対応する呼び出しと同じ順序で実行されます。Jakarta Messaging プロバイダーは、非同期送信メソッドを呼び出しているスレッドから CompletionListener を呼び出さないでください。

      メッセージオブジェクトの使用に関する制限 : 非同期送信を実行するアプリケーションは、メッセージオブジェクトが一度に 1 つの論理制御スレッドによってアクセスされるように設計されており、同時使用をサポートしないという制限を考慮する必要があります。

      send メソッドが返された後、アプリケーションは、CompletionListener の onCompletion または onException メソッドが呼び出されるまで、Message オブジェクトのヘッダー、プロパティ、本文を読み取ろうとしないでください。これは、この間に Jakarta Messaging プロバイダーが別のスレッドで Message オブジェクトを変更している可能性があるためです。send メソッドが返されてから CompletionListener が呼び出されるまでの間に、アプリケーションが Message オブジェクトにアクセスまたは変更しようとすると、Jakarta Messaging プロバイダーは JMSException をスローする場合があります。Jakarta Messaging プロバイダーが例外をスローしない場合、動作は未定義です。

      パラメーター:
      message - 送信するメッセージ
      completionListener - 送信が完了したときに通知される CompletionListener 
      例外:
      JMSException - 内部エラーが発生した場合
      MessageFormatException - 無効なメッセージが指定された場合。
      InvalidDestinationException - クライアントが無効な宛先を持つ MessageProducer でこのメソッドを使用する場合。
      IllegalArgumentExceptionSE - 指定された CompletionListener が NULL の場合
      UnsupportedOperationExceptionSE - クライアントが、作成時に宛先を指定しなかった MessageProducer でこのメソッドを使用する場合。
      導入:
      JMS 2.0
      関連事項:

    • send

      void send(Message message, int deliveryMode, int priority, long timeToLive, CompletionListener completionListener) throws JMSException
      メッセージを送信し、配信モード、優先度、存続時間を指定し、別のスレッドでメッセージの送信に関連する作業の一部を実行し、操作が完了したときに指定された CompletionListener に通知します。Jakarta Messaging は、これを「非同期送信」と呼びます。

      メッセージが正常に送信されると、Jakarta Messaging プロバイダーは、アプリケーションが指定した CompletionListener オブジェクトでコールバックメソッド onCompletion を呼び出します。そのコールバックが呼び出された場合のみ、アプリケーションは、通常の同期送信が実行された場合と同じ程度の信頼性でメッセージが正常に送信されたことを確認できます。この程度の信頼性を必要とするアプリケーションは、続行する前にコールバックが呼び出されるまで待機する必要があります。

      次の情報は、非同期送信が通常どのように実装されるかを示すことを目的としています。

      一部の Jakarta Messaging プロバイダーでは、通常の同期送信では、メッセージを リモート Jakarta Messaging サーバーに送信し、確認応答の受信を待ってから戻ります。このようなプロバイダーは、メッセージを リモート Jakarta Messaging サーバーに送信し、確認応答を待たずに戻ることで、非同期送信を実装することが期待されます。確認応答を受信すると、Jakarta Messaging プロバイダーは、アプリケーション指定の CompletionListener オブジェクトの onCompletion メソッドを呼び出してアプリケーションに通知します。何らかの理由で確認応答が受信されない場合は、Jakarta Messaging プロバイダーは CompletionListener の onException メソッドを呼び出してアプリケーションに通知します。

      Jakarta Messaging 仕様で許容される信頼性のレベルが低い場合、通常の同期送信では確認応答を待たないことがあります。その場合、非同期送信は同期送信と同様になることが予想されます。つまり、Jakarta Messaging プロバイダーはメッセージを リモート Jakarta Messaging サーバーに送信し、確認応答を待たずに戻ります。ただし、Jakarta Messaging プロバイダーは、アプリケーション指定の CompletionListener オブジェクトで onCompletion メソッドを呼び出すことにより、送信が完了したことをアプリケーションに通知します。

      以下に示す要件を満たしている限り、呼び出し元のスレッドで何を実行し、非同期で何を実行するかを正確に決定するのは Jakarta Messaging プロバイダーの責任です。

      サービス品質 : 送信操作が正常に完了した後、つまり通常の同期送信が実行された場合と同じ信頼度でメッセージが正常に送信された後、JMS プロバイダーは CompletionListener の onCompletion メソッドを呼び出す必要があります。これより前に CompletionListener を呼び出してはなりません。

      例外 : send メソッドの呼び出し中に例外が発生した場合は、send メソッドを呼び出しているスレッドで適切な例外がスローされる必要があります。この場合、Jakarta Messaging プロバイダーは CompletionListener の onCompletion または onException メソッドを呼び出してはなりません。send メソッドを呼び出しているスレッドでスローできない例外が発生した場合は、Jakarta Messaging プロバイダーは CompletionListener の onException メソッドを呼び出す必要があります。どちらの場合も、例外が発生した場合、メッセージが正常に送信されたかどうかは未定義です。

      メッセージの順序 : 同じ MessageProducer を使用して複数のメッセージを送信する場合は、Jakarta Messaging メッセージの順序の要件を満たす必要があります。これは、同期送信と非同期送信の組み合わせが実行された場合でも適用されます。アプリケーションは、次のメッセージを送信する前に非同期送信が完了するのを待つ必要はありません。

      クローズ、コミット、ロールバック : MessageProducer またはそのセッションまたは接続で close メソッドが呼び出された場合、Jakarta Messaging プロバイダーは、オブジェクトを閉じて戻る前に、不完全な送信操作が完了し、すべての CompletionListener コールバックが戻るまでブロックする必要があります。セッションがトランザクションされる（ローカルトランザクションを使用する）場合、セッションのコミットまたはロールバックメソッドが呼び出されると、Jakarta Messaging プロバイダーは、不完全な送信操作が完了し、コミットまたはロールバックを実行する前にすべての CompletionListener コールバックが返されるまでブロックする必要があります。エラーが発生しない限り、不完全な送信は正常に完了することが許可されている必要があります。

      CompletionListener コールバックメソッドはそれ自体の接続、セッションまたは MessageProducer close を呼び出さないでください > または、独自のセッションで commit または rollback を呼び出します。これを行うと、 close 、 commit 、または rollback が IllegalStateException をスローします。

      Jakarta EE での使用に関する制限このメソッドは、Jakarta EE EJB または Web コンテナーでは使用しないでください。これを行うと、JMSException がスローされる可能性がありますが、これは保証されていません。

      メッセージヘッダー Jakarta Messaging は、" 送信時の Jakarta Messaging プロバイダー " によって設定する必要がある、多数のメッセージヘッダーフィールドとメッセージプロパティを定義します。送信が非同期の場合、これらのフィールドとプロパティは、CompletionListener が呼び出された後にのみ、送信クライアントでアクセスできます。CompletionListener の onException メソッドが呼び出されると、これらのメッセージヘッダーフィールドとプロパティの状態は未定義になります。

      スレッドの制限 : 非同期送信を実行するアプリケーションは、JMS で定義されているスレッド制限を確認する必要があります。これは、セッションが一度に 1 つのスレッドのみによって使用される可能性があることを意味します。

      CompletionListener を設定しても、セッションは CompletionListener を呼び出す制御スレッド専用にはなりません。アプリケーションスレッドは、非同期送信を実行した後もセッションを引き続き使用できます。ただし、アプリケーションスレッドが同時にセッションを使用している可能性がある場合は、 CompletionListener のコールバックメソッドでセッションを使用しないでください。

      Jakarta Messaging プロバイダーによる CompletionListener の使用 : セッションは、一度に 1 つの CompletionListener コールバックメソッドのみを呼び出します。特定の MessageProducer について、コールバック（onCompletion と onException の両方）は、非同期送信メソッドへの対応する呼び出しと同じ順序で実行されます。Jakarta Messaging プロバイダーは、非同期送信メソッドを呼び出しているスレッドから CompletionListener を呼び出さないでください。

      メッセージオブジェクトの使用に関する制限 : 非同期送信を実行するアプリケーションは、メッセージオブジェクトが一度に 1 つの論理制御スレッドによってアクセスされるように設計されており、同時使用をサポートしないという制限を考慮する必要があります。

      send メソッドが返された後、アプリケーションは、CompletionListener の onCompletion または onException メソッドが呼び出されるまで、Message オブジェクトのヘッダー、プロパティ、本文を読み取ろうとしないでください。これは、この間に Jakarta Messaging プロバイダーが別のスレッドで Message オブジェクトを変更している可能性があるためです。send メソッドが返されてから CompletionListener が呼び出されるまでの間に、アプリケーションが Message オブジェクトにアクセスまたは変更しようとすると、Jakarta Messaging プロバイダーは JMSException をスローする場合があります。Jakarta Messaging プロバイダーが例外をスローしない場合、動作は未定義です。

      パラメーター:
      message - 送信するメッセージ
      deliveryMode - 使用する配信モード
      priority - このメッセージの優先度
      timeToLive - メッセージの存続期間 (ミリ秒単位)
      completionListener - 送信が完了したときに通知される CompletionListener 
      例外:
      JMSException - 内部エラーが発生した場合
      MessageFormatException - 無効なメッセージが指定された場合。
      InvalidDestinationException - クライアントが無効な宛先を持つ MessageProducer でこのメソッドを使用する場合。
      IllegalArgumentExceptionSE - 指定された CompletionListener が NULL の場合
      UnsupportedOperationExceptionSE - クライアントが、作成時に宛先を指定しなかった MessageProducer でこのメソッドを使用する場合。
      導入:
      JMS 2.0
      関連事項:

    • send

      void send(Destination destination, Message message, CompletionListener completionListener) throws JMSException
      MessageProducer のデフォルトの配信モード、優先度、存続時間を使用して、不明なメッセージプロデューサーの宛先にメッセージを送信し、別のスレッドでメッセージを送信し、指定された CompletionListener に通知する作業の一部を実行します。操作が完了したとき。Jakarta Messaging は、これを「非同期送信」と呼びます。

      通常、メッセージプロデューサーには作成時に宛先が割り当てられます。ただし、Jakarta Messaging API は、未確認のメッセージプロデューサーもサポートしているため、メッセージが送信されるたびに宛先を指定する必要があります。

      メッセージが正常に送信されると、Jakarta Messaging プロバイダーは、アプリケーションが指定した CompletionListener オブジェクトでコールバックメソッド onCompletion を呼び出します。そのコールバックが呼び出された場合のみ、アプリケーションは、通常の同期送信が実行された場合と同じ程度の信頼性でメッセージが正常に送信されたことを確認できます。この程度の信頼性を必要とするアプリケーションは、続行する前にコールバックが呼び出されるまで待機する必要があります。

      次の情報は、非同期送信が通常どのように実装されるかを示すことを目的としています。

      一部の Jakarta Messaging プロバイダーでは、通常の同期送信では、メッセージを リモート Jakarta Messaging サーバーに送信し、確認応答の受信を待ってから戻ります。このようなプロバイダーは、メッセージを リモート Jakarta Messaging サーバーに送信し、確認応答を待たずに戻ることで、非同期送信を実装することが期待されます。確認応答を受信すると、Jakarta Messaging プロバイダーは、アプリケーション指定の CompletionListener オブジェクトの onCompletion メソッドを呼び出してアプリケーションに通知します。何らかの理由で確認応答が受信されない場合は、Jakarta Messaging プロバイダーは CompletionListener の onException メソッドを呼び出してアプリケーションに通知します。

      Jakarta Messaging 仕様で許容される信頼性のレベルが低い場合、通常の同期送信では確認応答を待たないことがあります。その場合、非同期送信は同期送信と同様になることが予想されます。つまり、Jakarta Messaging プロバイダーはメッセージを リモート Jakarta Messaging サーバーに送信し、確認応答を待たずに戻ります。ただし、Jakarta Messaging プロバイダーは、アプリケーション指定の CompletionListener オブジェクトで onCompletion メソッドを呼び出すことにより、送信が完了したことをアプリケーションに通知します。

      以下に示す要件を満たしている限り、呼び出し元のスレッドで何を実行し、非同期で何を実行するかを正確に決定するのは Jakarta Messaging プロバイダーの責任です。

      サービス品質 : 送信操作が正常に完了した後、つまり通常の同期送信が実行された場合と同じ信頼度でメッセージが正常に送信された後、JMS プロバイダーは CompletionListener の onCompletion メソッドを呼び出す必要があります。これより前に CompletionListener を呼び出してはなりません。

      例外 : send メソッドの呼び出し中に例外が発生した場合は、send メソッドを呼び出しているスレッドで適切な例外がスローされる必要があります。この場合、Jakarta Messaging プロバイダーは CompletionListener の onCompletion または onException メソッドを呼び出してはなりません。send メソッドを呼び出しているスレッドでスローできない例外が発生した場合は、Jakarta Messaging プロバイダーは CompletionListener の onException メソッドを呼び出す必要があります。どちらの場合も、例外が発生した場合、メッセージが正常に送信されたかどうかは未定義です。

      メッセージの順序 : 同じ MessageProducer を使用して複数のメッセージを送信する場合は、Jakarta Messaging メッセージの順序の要件を満たす必要があります。これは、同期送信と非同期送信の組み合わせが実行された場合でも適用されます。アプリケーションは、次のメッセージを送信する前に非同期送信が完了するのを待つ必要はありません。

      クローズ、コミット、ロールバック : MessageProducer またはそのセッションまたは接続で close メソッドが呼び出された場合、Jakarta Messaging プロバイダーは、オブジェクトを閉じて戻る前に、不完全な送信操作が完了し、すべての CompletionListener コールバックが戻るまでブロックする必要があります。セッションがトランザクションされる（ローカルトランザクションを使用する）場合、セッションのコミットまたはロールバックメソッドが呼び出されると、Jakarta Messaging プロバイダーは、不完全な送信操作が完了し、コミットまたはロールバックを実行する前にすべての CompletionListener コールバックが返されるまでブロックする必要があります。エラーが発生しない限り、不完全な送信は正常に完了することが許可されている必要があります。

      CompletionListener コールバックメソッドはそれ自体の接続、セッションまたは MessageProducer close を呼び出さないでください > または、独自のセッションで commit または rollback を呼び出します。これを行うと、 close 、 commit 、または rollback が IllegalStateException をスローします。

      Jakarta EE での使用に関する制限このメソッドは、Jakarta EE EJB または Web コンテナーでは使用しないでください。これを行うと、JMSException がスローされる可能性がありますが、これは保証されていません。

      メッセージヘッダー Jakarta Messaging は、" 送信時の Jakarta Messaging プロバイダー " によって設定する必要がある、多数のメッセージヘッダーフィールドとメッセージプロパティを定義します。送信が非同期の場合、これらのフィールドとプロパティは、CompletionListener が呼び出された後にのみ、送信クライアントでアクセスできます。CompletionListener の onException メソッドが呼び出されると、これらのメッセージヘッダーフィールドとプロパティの状態は未定義になります。

      スレッドの制限 : 非同期送信を実行するアプリケーションは、JMS で定義されているスレッド制限を確認する必要があります。これは、セッションが一度に 1 つのスレッドのみによって使用される可能性があることを意味します。

      CompletionListener を設定しても、セッションは CompletionListener を呼び出す制御スレッド専用にはなりません。アプリケーションスレッドは、非同期送信を実行した後もセッションを引き続き使用できます。ただし、アプリケーションスレッドが同時にセッションを使用している可能性がある場合は、 CompletionListener のコールバックメソッドでセッションを使用しないでください。

      Jakarta Messaging プロバイダーによる CompletionListener の使用 : セッションは、一度に 1 つの CompletionListener コールバックメソッドのみを呼び出します。特定の MessageProducer について、コールバック（onCompletion と onException の両方）は、非同期送信メソッドへの対応する呼び出しと同じ順序で実行されます。Jakarta Messaging プロバイダーは、非同期送信メソッドを呼び出しているスレッドから CompletionListener を呼び出さないでください。

      メッセージオブジェクトの使用に関する制限 : 非同期送信を実行するアプリケーションは、メッセージオブジェクトが一度に 1 つの論理制御スレッドによってアクセスされるように設計されており、同時使用をサポートしないという制限を考慮する必要があります。

      send メソッドが返された後、アプリケーションは、CompletionListener の onCompletion または onException メソッドが呼び出されるまで、Message オブジェクトのヘッダー、プロパティ、本文を読み取ろうとしないでください。これは、この間に Jakarta Messaging プロバイダーが別のスレッドで Message オブジェクトを変更している可能性があるためです。send メソッドが返されてから CompletionListener が呼び出されるまでの間に、アプリケーションが Message オブジェクトにアクセスまたは変更しようとすると、Jakarta Messaging プロバイダーは JMSException をスローする場合があります。Jakarta Messaging プロバイダーが例外をスローしない場合、動作は未定義です。

      パラメーター:
      destination - このメッセージの送信先
      message - 送信するメッセージ
      completionListener - 送信が完了したときに通知される CompletionListener 
      例外:
      JMSException - 内部エラーが発生した場合
      MessageFormatException - 無効なメッセージが指定された場合。
      InvalidDestinationException - クライアントが無効な宛先でこのメソッドを使用する場合
      IllegalArgumentExceptionSE - 指定された CompletionListener が NULL の場合
      UnsupportedOperationExceptionSE - クライアントが作成時に宛先を指定した MessageProducer でこのメソッドを使用する場合。
      導入:
      JMS 2.0
      関連事項:

    • send

      void send(Destination destination, Message message, int deliveryMode, int priority, long timeToLive, CompletionListener completionListener) throws JMSException
      不明なメッセージプロデューサーの宛先にメッセージを送信し、配信モード、優先度、存続時間を指定し、別のスレッドでメッセージを送信する作業の一部を実行し、指定された CompletionListener に通知します。操作が完了しました。Jakarta Messaging は、これを「非同期送信」と呼びます。

      通常、メッセージプロデューサーには作成時に宛先が割り当てられます。ただし、Jakarta Messaging API は、未確認のメッセージプロデューサーもサポートしているため、メッセージが送信されるたびに宛先を指定する必要があります。

      メッセージが正常に送信されると、Jakarta Messaging プロバイダーは、アプリケーションが指定した CompletionListener オブジェクトでコールバックメソッド onCompletion を呼び出します。そのコールバックが呼び出された場合のみ、アプリケーションは、通常の同期送信が実行された場合と同じ程度の信頼性でメッセージが正常に送信されたことを確認できます。この程度の信頼性を必要とするアプリケーションは、続行する前にコールバックが呼び出されるまで待機する必要があります。

      次の情報は、非同期送信が通常どのように実装されるかを示すことを目的としています。

      一部の Jakarta Messaging プロバイダーでは、通常の同期送信では、メッセージを リモート Jakarta Messaging サーバーに送信し、確認応答の受信を待ってから戻ります。このようなプロバイダーは、メッセージを リモート Jakarta Messaging サーバーに送信し、確認応答を待たずに戻ることで、非同期送信を実装することが期待されます。確認応答を受信すると、Jakarta Messaging プロバイダーは、アプリケーション指定の CompletionListener オブジェクトの onCompletion メソッドを呼び出してアプリケーションに通知します。何らかの理由で確認応答が受信されない場合は、Jakarta Messaging プロバイダーは CompletionListener の onException メソッドを呼び出してアプリケーションに通知します。

      Jakarta Messaging 仕様で許容される信頼性のレベルが低い場合、通常の同期送信では確認応答を待たないことがあります。その場合、非同期送信は同期送信と同様になることが予想されます。つまり、Jakarta Messaging プロバイダーはメッセージを リモート Jakarta Messaging サーバーに送信し、確認応答を待たずに戻ります。ただし、Jakarta Messaging プロバイダーは、アプリケーション指定の CompletionListener オブジェクトで onCompletion メソッドを呼び出すことにより、送信が完了したことをアプリケーションに通知します。

      以下に示す要件を満たしている限り、呼び出し元のスレッドで何を実行し、非同期で何を実行するかを正確に決定するのは Jakarta Messaging プロバイダーの責任です。

      サービス品質 : 送信操作が正常に完了した後、つまり通常の同期送信が実行された場合と同じ信頼度でメッセージが正常に送信された後、JMS プロバイダーは CompletionListener の onCompletion メソッドを呼び出す必要があります。これより前に CompletionListener を呼び出してはなりません。

      例外 : send メソッドの呼び出し中に例外が発生した場合は、send メソッドを呼び出しているスレッドで適切な例外がスローされる必要があります。この場合、Jakarta Messaging プロバイダーは CompletionListener の onCompletion または onException メソッドを呼び出してはなりません。send メソッドを呼び出しているスレッドでスローできない例外が発生した場合は、Jakarta Messaging プロバイダーは CompletionListener の onException メソッドを呼び出す必要があります。どちらの場合も、例外が発生した場合、メッセージが正常に送信されたかどうかは未定義です。

      メッセージの順序 : 同じ MessageProducer を使用して複数のメッセージを送信する場合は、Jakarta Messaging メッセージの順序の要件を満たす必要があります。これは、同期送信と非同期送信の組み合わせが実行された場合でも適用されます。アプリケーションは、次のメッセージを送信する前に非同期送信が完了するのを待つ必要はありません。

      クローズ、コミット、ロールバック : MessageProducer またはそのセッションまたは接続で close メソッドが呼び出された場合、Jakarta Messaging プロバイダーは、オブジェクトを閉じて戻る前に、不完全な送信操作が完了し、すべての CompletionListener コールバックが戻るまでブロックする必要があります。セッションがトランザクションされる（ローカルトランザクションを使用する）場合、セッションのコミットまたはロールバックメソッドが呼び出されると、Jakarta Messaging プロバイダーは、不完全な送信操作が完了し、コミットまたはロールバックを実行する前にすべての CompletionListener コールバックが返されるまでブロックする必要があります。エラーが発生しない限り、不完全な送信は正常に完了することが許可されている必要があります。

      CompletionListener コールバックメソッドはそれ自体の接続、セッションまたは MessageProducer close を呼び出さないでください > または、独自のセッションで commit または rollback を呼び出します。これを行うと、 close 、 commit 、または rollback が IllegalStateException をスローします。

      Jakarta EE での使用に関する制限このメソッドは、Jakarta EE EJB または Web コンテナーでは使用しないでください。これを行うと、JMSException がスローされる可能性がありますが、これは保証されていません。

      メッセージヘッダー Jakarta Messaging は、" 送信時の Jakarta Messaging プロバイダー " によって設定する必要がある、多数のメッセージヘッダーフィールドとメッセージプロパティを定義します。送信が非同期の場合、これらのフィールドとプロパティは、CompletionListener が呼び出された後にのみ、送信クライアントでアクセスできます。CompletionListener の onException メソッドが呼び出されると、これらのメッセージヘッダーフィールドとプロパティの状態は未定義になります。

      スレッドの制限 : 非同期送信を実行するアプリケーションは、JMS で定義されているスレッド制限を確認する必要があります。これは、セッションが一度に 1 つのスレッドのみによって使用される可能性があることを意味します。

      CompletionListener を設定しても、セッションは CompletionListener を呼び出す制御スレッド専用にはなりません。アプリケーションスレッドは、非同期送信を実行した後もセッションを引き続き使用できます。ただし、アプリケーションスレッドが同時にセッションを使用している可能性がある場合は、 CompletionListener のコールバックメソッドでセッションを使用しないでください。

      Jakarta Messaging プロバイダーによる CompletionListener の使用 : セッションは、一度に 1 つの CompletionListener コールバックメソッドのみを呼び出します。特定の MessageProducer について、コールバック（onCompletion と onException の両方）は、非同期送信メソッドへの対応する呼び出しと同じ順序で実行されます。Jakarta Messaging プロバイダーは、非同期送信メソッドを呼び出しているスレッドから CompletionListener を呼び出さないでください。

      メッセージオブジェクトの使用に関する制限 : 非同期送信を実行するアプリケーションは、メッセージオブジェクトが一度に 1 つの論理制御スレッドによってアクセスされるように設計されており、同時使用をサポートしないという制限を考慮する必要があります。

      send メソッドが返された後、アプリケーションは、CompletionListener の onCompletion または onException メソッドが呼び出されるまで、Message オブジェクトのヘッダー、プロパティ、本文を読み取ろうとしないでください。これは、この間に Jakarta Messaging プロバイダーが別のスレッドで Message オブジェクトを変更している可能性があるためです。send メソッドが返されてから CompletionListener が呼び出されるまでの間に、アプリケーションが Message オブジェクトにアクセスまたは変更しようとすると、Jakarta Messaging プロバイダーは JMSException をスローする場合があります。Jakarta Messaging プロバイダーが例外をスローしない場合、動作は未定義です。

      パラメーター:
      destination - このメッセージの送信先
      message - 送信するメッセージ
      deliveryMode - 使用する配信モード
      priority - このメッセージの優先度
      timeToLive - メッセージの存続期間 (ミリ秒単位)
      completionListener - 送信が完了したときに通知される CompletionListener 
      例外:
      JMSException - 内部エラーが発生した場合
      MessageFormatException - 無効なメッセージが指定された場合。
      InvalidDestinationException - クライアントが無効な宛先でこのメソッドを使用する場合。
      IllegalArgumentExceptionSE - 指定された CompletionListener が NULL の場合
      UnsupportedOperationExceptionSE - クライアントが作成時に宛先を指定した MessageProducer でこのメソッドを使用する場合。
      導入:
      JMS 2.0
      関連事項: