パッケージ jakarta.jms

インターフェース JMSConsumer

  • すべてのスーパーインターフェース:
    AutoCloseableSE
    public interface JMSConsumer
extends AutoCloseableSE
    Jakarta Messaging 2.0 用に導入された簡略化された Jakarta Messaging API を使用するクライアントは、JMSConsumer オブジェクトを使用して、キューまたはトピックからメッセージを受信します。JMSConsumer オブジェクトは、Queue または Topic オブジェクトを JMSContext の createConsumer メソッドの 1 つに渡すことによって作成できます。または、Topic オブジェクトを JMSContext の createSharedConsumer または createDurableConsumer メソッドのいずれかに渡すこと

    JMSConsumer は、メッセージセレクターを使用して作成できます。メッセージセレクターを使用すると、クライアントは JMSConsumer に配信されるメッセージをセレクターに一致するメッセージに制限できます。

    クライアントは、JMSConsumer のメッセージを同期的に受信するか、JMSConsumer にメッセージの到着時に非同期で配信させることができます。

    同期受信の場合、クライアントは、receive メソッドの 1 つを使用して、JMSConsumer から次のメッセージをリクエストできます。クライアントがポーリングしたり、次のメッセージを待機したりできるようにする receive にはいくつかのバリエーションがあります。

    非同期配信の場合、クライアントは MessageListener オブジェクトを JMSConsumer に登録できます。メッセージが JMSConsumer に到着すると、MessageListener の onMessage メソッドを呼び出してメッセージを配信します。

    MessageListener が例外をスローするのはクライアントプログラミングエラーです。

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

    • メソッドのサマリー

      すべてのメソッド   インスタンスメソッド   抽象メソッド  
      修飾子と型 メソッド 説明
      voidclose()
      JMSConsumer を閉じます。
      MessageListenergetMessageListener()
      JMSConsumer の MessageListener を取得します。
      StringSEgetMessageSelector()
      この JMSConsumer のメッセージセレクター式を取得します。
      Messagereceive()
      この JMSConsumer 用に作成された次のメッセージを受け取ります。
      Messagereceive​(long timeout)
      指定されたタイムアウト間隔内に到着する次のメッセージを受信します。
      <T> TreceiveBody​(ClassSE<T> c)
      この JMSConsumer に対して生成された次のメッセージを受信し、その本文を指定された型のオブジェクトとして返します。
      <T> TreceiveBody​(ClassSE<T> c, long timeout)
      この JMSConsumer に対して生成された、指定されたタイムアウト期間内に到着する次のメッセージを受信し、その本文を指定された型のオブジェクトとして返します。
      <T> TreceiveBodyNoWait​(ClassSE<T> c)
      この JMSConsumer がすぐに使用可能になった場合に生成される次のメッセージを受信し、その本文を指定された型のオブジェクトとして返します。
      MessagereceiveNoWait()
      次のメッセージがすぐに利用可能な場合、受信します。
      voidsetMessageListener​(MessageListener listener)
      JMSConsumer の MessageListener を設定します。

    • メソッドの詳細

      • getMessageSelector

        StringSE getMessageSelector()
        この JMSConsumer のメッセージセレクター式を取得します。
        戻り値:
        この JMSConsumer のメッセージセレクター、または JMSConsumer のメッセージセレクターが存在しない場合は null (つまり、メッセージセレクターが設定されていないか、null または空の文字列に設定されている場合)
        例外:
        JMSRuntimeException - 内部エラーが原因で Jakarta Messaging プロバイダーがメッセージセレクターの取得に失敗した場合。

      • getMessageListener

        MessageListener getMessageListener()
                            throws JMSRuntimeException
        JMSConsumer の MessageListener を取得します。

        このメソッドは、Jakarta EE Web または EJB アプリケーションでは使用しないでください。保証されていませんが、JMSRuntimeException がスローされる可能性があります。

        戻り値:
        JMSConsumer の MessageListener、または設定されていない場合は null
        例外:
        JMSRuntimeException - 次のいずれかの理由で Jakarta Messaging プロバイダーが MessageListener の取得に失敗した場合:
        • 内部エラーが発生した、または
        • このメソッドは Jakarta EE Web または EJB アプリケーションで呼び出されました (この場合、例外がスローされることは保証されていませんが)
        関連事項:
        setMessageListener(jakarta.jms.MessageListener)

      • setMessageListener

        void setMessageListener​(MessageListener listener)
                 throws JMSRuntimeException
        JMSConsumer の MessageListener を設定します。

        MessageListener を null に設定することは、JMSConsumer の MessageListener を設定解除することと同じです。

        メッセージが既存のリスナーによって消費されている間、または JMSConsumer がメッセージを同期的に消費するために使用されているときに、このメソッドを呼び出す効果は定義されていません。

        このメソッドは、Jakarta EE Web または EJB アプリケーションでは使用しないでください。保証されていませんが、JMSRuntimeException がスローされる可能性があります。

        パラメーター:
        listener - メッセージの配信先のリスナー
        例外:
        JMSRuntimeException - Jakarta Messaging プロバイダーが次のいずれかの理由で JMSConsumer の MessageListener の設定に失敗した場合:
        • 内部エラーが発生した、または
        • このメソッドは Jakarta EE Web または EJB アプリケーションで呼び出されました (この場合、例外がスローされることは保証されていませんが)
        関連事項:
        getMessageListener()

      • receive

        Message receive()
        この JMSConsumer 用に作成された次のメッセージを受け取ります。

        この呼び出しは、メッセージが生成されるまで、またはこの JMSConsumer が閉じられるまで、無期限にブロックされます。

        この receive がトランザクション内で実行される場合、JMSConsumer は、トランザクションがコミットされるまでメッセージを保持します。

        戻り値:
        この JMSConsumer に対して生成される次のメッセージ、またはこの JMSConsumer が同時に閉じられている場合は null
        例外:
        JMSRuntimeException - 内部エラーのために Jakarta Messaging プロバイダーが次のメッセージを受信できない場合。

      • receive

        Message receive​(long timeout)
        指定されたタイムアウト間隔内に到着する次のメッセージを受信します。

        この呼び出しは、メッセージが到着するか、タイムアウトが期限切れになるか、この JMSConsumer が閉じられるまでブロックされます。ゼロの timeout が期限切れになることはなく、呼び出しは無期限にブロックされます。

        パラメーター:
        timeout - タイムアウト値 (ミリ秒単位)
        戻り値:
        この JMSConsumer に対して生成される次のメッセージ、またはタイムアウトが期限切れになるか、この JMSConsumer が同時に閉じられる場合は null
        例外:
        JMSRuntimeException - 内部エラーのために Jakarta Messaging プロバイダーが次のメッセージを受信できない場合。

      • receiveNoWait

        Message receiveNoWait()
        次のメッセージがすぐに利用可能な場合、受信します。
        戻り値:
        この JMSConsumer に対して生成される次のメッセージ、または使用できない場合は null
        例外:
        JMSRuntimeException - 内部エラーのために Jakarta Messaging プロバイダーが次のメッセージを受信できない場合。

      • close

        void close()
        JMSConsumer を閉じます。

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

        この呼び出しは、このコンシューマーで進行中の receive 呼び出しが完了するまでブロックされます。ブロックされた receive 呼び出しは、このコンシューマーが閉じられると null を返します。

        メッセージリスナーが別のスレッドで進行しているときにこのメソッドが呼び出されると、メッセージリスナーが完了するまでブロックされます。

        このメソッドは、それ自体のコンシューマー上のメッセージリスナーの onMessage メソッドから呼び出すことができます。このメソッドが戻った後、onMessage メソッドは正常に完了することができます。

        このメソッドは、同時に呼び出すことができる唯一の JMSConsumer メソッドです。

        次で指定:
        インターフェース AutoCloseableSE の close 
        例外:
        JMSRuntimeException - 内部エラーが原因で Jakarta Messaging プロバイダーがコンシューマーを閉じることができない場合。

      • receiveBody

        <T> T receiveBody​(ClassSE<T> c)
        この JMSConsumer に対して生成された次のメッセージを受信し、その本文を指定された型のオブジェクトとして返します。このメソッドは、メッセージに指定された型に割り当てることができる本文が含まれている限り、StreamMessage と Message を除くすべての型のメッセージを受信するために使用できます。これは、指定されたクラスまたはインターフェースが、メッセージ本文のクラスと同じであるか、スーパークラスまたはスーパーインターフェースである必要があることを意味します。メッセージがサポートされている型の 1 つではない場合、メッセージの本文を指定された型に割り当てることができない場合、またはメッセージに本文がない場合は、MessageFormatRuntimeException がスローされます。

        このメソッドは、メッセージヘッダーまたはプロパティ（JMSRedelivered メッセージヘッダーフィールドや JMSXDeliveryCount メッセージプロパティなど）へのアクセスを許可しないため、アプリケーションがそれらにアクセスする必要がない場合にのみ使用する必要があります。

        この呼び出しは、メッセージが生成されるまで、またはこの JMSConsumer が閉じられるまで、無期限にブロックされます。

        このメソッドがトランザクション内で呼び出された場合、JMSConsumer は、トランザクションがコミットされるまでメッセージを保持します。

        このメソッドが MessageFormatRuntimeException をスローした結果は、セッションモードによって異なります。

        • AUTO_ACKNOWLEDGE または DUPS_OK_ACKNOWLEDGE: Jakarta Messaging プロバイダーは、receiveBody への呼び出しが失敗しなかったかのように動作します。メッセージは、後続のメッセージの前に再度配信されます。これは再配信とは見なされず、JMSRedelivered メッセージヘッダーフィールドが設定されたり、JMSXDeliveryCount メッセージプロパティがインクリメントされたりすることはありません。
        • CLIENT_ACKNOWLEDGE: Jakarta Messaging プロバイダーは、receiveBody への呼び出しが成功したかのように動作し、メッセージを再度配信しません。CLIENT_ACKNOWLEDGE のセッションモードで配信される他のメッセージと同様に、JMSContext で acknowledge が呼び出されるまで、メッセージは確認応答されません。アプリケーションが失敗したメッセージの再配信を希望する場合は、JMSContext で recover を呼び出す必要があります。再配信されたメッセージの JMSRedelivered メッセージヘッダーフィールドが設定され、その JMSXDeliveryCount メッセージプロパティがインクリメントされます。
        • 取引セッション: Jakarta Messaging プロバイダーは、receiveBody への呼び出しが成功したかのように動作し、メッセージを再度配信しません。トランザクションセッションで配信される他のメッセージと同様に、トランザクションは、アプリケーションによってコミットまたはロールバックされるまで、コミットされないままになります。アプリケーションが失敗したメッセージの再配信を希望する場合は、トランザクションをロールバックする必要があります。再配信されたメッセージの JMSRedelivered メッセージヘッダーフィールドが設定され、その JMSXDeliveryCount メッセージプロパティがインクリメントされます。
        型パラメーター:
        T - メッセージ本文の型
        パラメーター:
        c - 次のメッセージの本文を割り当てる型。
        次のメッセージが TextMessage であると予想される場合は、これを String.class または String が割り当て可能な別のクラスに設定する必要があります。
        次のメッセージが ObjectMessage であると予想される場合は、これを java.io.Serializable.class または本文が割り当て可能な別のクラスに設定する必要があります。
        次のメッセージが MapMessage であると予想される場合は、これを java.util.Map.class （または java.lang.Object.class）に設定する必要があります。
        次のメッセージが BytesMessage であると予想される場合は、これを byte[].class （または java.lang.Object.class）に設定する必要があります。
        戻り値:
        この JMSConsumer に対して生成される次のメッセージの本文、またはこの JMSConsumer が同時に閉じられている場合は null
        例外:
        MessageFormatRuntimeException -
        • メッセージが上記のサポートされている型のいずれでもない場合
        • メッセージ本文を指定された型に割り当てることができない場合
        • メッセージに本文がない場合
        • メッセージが ObjectMessage であり、オブジェクトの逆直列化が失敗した場合。
        JMSRuntimeException - 内部エラーが原因で Jakarta Messaging プロバイダーが次のメッセージを受信できない場合

      • receiveBody

        <T> T receiveBody​(ClassSE<T> c,
                  long timeout)
        この JMSConsumer に対して生成された、指定されたタイムアウト期間内に到着する次のメッセージを受信し、その本文を指定された型のオブジェクトとして返します。このメソッドは、メッセージに指定された型に割り当てることができる本文が含まれている限り、StreamMessage と Message を除くすべての型のメッセージを受信するために使用できます。これは、指定されたクラスまたはインターフェースが、メッセージ本文のクラスと同じであるか、スーパークラスまたはスーパーインターフェースである必要があることを意味します。メッセージがサポートされている型の 1 つではない場合、メッセージの本文を指定された型に割り当てることができない場合、またはメッセージに本文がない場合は、MessageFormatRuntimeException がスローされます。

        このメソッドは、メッセージヘッダーまたはプロパティ（JMSRedelivered メッセージヘッダーフィールドや JMSXDeliveryCount メッセージプロパティなど）へのアクセスを許可しないため、アプリケーションがそれらにアクセスする必要がない場合にのみ使用する必要があります。

        この呼び出しは、メッセージが到着するか、タイムアウトが期限切れになるか、この JMSConsumer が閉じられるまでブロックされます。ゼロのタイムアウトが期限切れになることはなく、呼び出しは無期限にブロックされます。

        このメソッドがトランザクション内で呼び出された場合、JMSConsumer は、トランザクションがコミットされるまでメッセージを保持します。

        このメソッドが MessageFormatRuntimeException をスローした結果は、セッションモードによって異なります。

        • AUTO_ACKNOWLEDGE または DUPS_OK_ACKNOWLEDGE: Jakarta Messaging プロバイダーは、receiveBody への呼び出しが失敗しなかったかのように動作します。メッセージは、後続のメッセージの前に再度配信されます。これは再配信とは見なされず、JMSRedelivered メッセージヘッダーフィールドが設定されたり、JMSXDeliveryCount メッセージプロパティがインクリメントされたりすることはありません。
        • CLIENT_ACKNOWLEDGE: Jakarta Messaging プロバイダーは、receiveBody への呼び出しが成功したかのように動作し、メッセージを再度配信しません。CLIENT_ACKNOWLEDGE のセッションモードで配信される他のメッセージと同様に、JMSContext で acknowledge が呼び出されるまで、メッセージは確認応答されません。アプリケーションが失敗したメッセージの再配信を希望する場合は、JMSContext で recover を呼び出す必要があります。再配信されたメッセージの JMSRedelivered メッセージヘッダーフィールドが設定され、その JMSXDeliveryCount メッセージプロパティがインクリメントされます。
        • 取引セッション: Jakarta Messaging プロバイダーは、receiveBody への呼び出しが成功したかのように動作し、メッセージを再度配信しません。トランザクションセッションで配信される他のメッセージと同様に、トランザクションは、アプリケーションによってコミットまたはロールバックされるまで、コミットされないままになります。アプリケーションが失敗したメッセージの再配信を希望する場合は、トランザクションをロールバックする必要があります。再配信されたメッセージの JMSRedelivered メッセージヘッダーフィールドが設定され、その JMSXDeliveryCount メッセージプロパティがインクリメントされます。
        型パラメーター:
        T - メッセージ本文型
        パラメーター:
        c - 次のメッセージの本文を割り当てる型。
        次のメッセージが TextMessage であると予想される場合は、これを String.class または String が割り当て可能な別のクラスに設定する必要があります。
        次のメッセージが ObjectMessage であると予想される場合は、これを java.io.Serializable.class または本文が割り当て可能な別のクラスに設定する必要があります。
        次のメッセージが MapMessage であると予想される場合は、これを java.util.Map.class （または java.lang.Object.class）に設定する必要があります。
        次のメッセージが BytesMessage であると予想される場合は、これを byte[].class （または java.lang.Object.class）に設定する必要があります。
        timeout - このメソッドがブロックする最大時間。ゼロは無期限にブロックすることを意味します。
        戻り値:
        この JMSConsumer に対して生成される次のメッセージの本文、またはタイムアウトが期限切れになるか、この JMSConsumer が同時に閉じられる場合は null
        例外:
        MessageFormatRuntimeException -
        • メッセージが上記のサポートされている型のいずれでもない場合
        • メッセージ本文を指定された型に割り当てることができない場合
        • メッセージに本文がない場合
        • メッセージが ObjectMessage であり、オブジェクトの逆直列化が失敗した場合。
        JMSRuntimeException - 内部エラーが原因で Jakarta Messaging プロバイダーが次のメッセージを受信できない場合

      • receiveBodyNoWait

        <T> T receiveBodyNoWait​(ClassSE<T> c)
        この JMSConsumer がすぐに使用可能になった場合に生成される次のメッセージを受信し、その本文を指定された型のオブジェクトとして返します。このメソッドは、メッセージに指定された型に割り当てることができる本文が含まれている限り、StreamMessage と Message を除くすべての型のメッセージを受信するために使用できます。これは、指定されたクラスまたはインターフェースが、メッセージ本文のクラスと同じであるか、スーパークラスまたはスーパーインターフェースである必要があることを意味します。メッセージがサポートされている型の 1 つではない場合、メッセージの本文を指定された型に割り当てることができない場合、またはメッセージに本文がない場合は、MessageFormatRuntimeException がスローされます。

        このメソッドは、メッセージヘッダーまたはプロパティ（JMSRedelivered メッセージヘッダーフィールドや JMSXDeliveryCount メッセージプロパティなど）へのアクセスを許可しないため、アプリケーションがそれらにアクセスする必要がない場合にのみ使用する必要があります。

        メッセージがすぐに利用できない場合は、null が返されます。

        このメソッドがトランザクション内で呼び出された場合、JMSConsumer は、トランザクションがコミットされるまでメッセージを保持します。

        このメソッドが MessageFormatRuntimeException をスローした結果は、セッションモードによって異なります。

        • AUTO_ACKNOWLEDGE または DUPS_OK_ACKNOWLEDGE: Jakarta Messaging プロバイダーは、receiveBodyNoWait への呼び出しが失敗しなかったかのように動作します。メッセージは、後続のメッセージの前に再度配信されます。これは再配信とは見なされず、JMSRedelivered メッセージヘッダーフィールドが設定されたり、JMSXDeliveryCount メッセージプロパティがインクリメントされたりすることはありません。
        • CLIENT_ACKNOWLEDGE: Jakarta Messaging プロバイダーは、receiveBodyNoWait への呼び出しが成功したかのように動作し、メッセージを再度配信しません。CLIENT_ACKNOWLEDGE のセッションモードで配信される他のメッセージと同様に、JMSContext で acknowledge が呼び出されるまで、メッセージは確認応答されません。アプリケーションが失敗したメッセージの再配信を希望する場合は、JMSContext で recover を呼び出す必要があります。再配信されたメッセージの JMSRedelivered メッセージヘッダーフィールドが設定され、その JMSXDeliveryCount メッセージプロパティがインクリメントされます。
        • 取引セッション: Jakarta Messaging プロバイダーは、receiveBodyNoWait への呼び出しが成功したかのように動作し、メッセージを再度配信しません。トランザクションセッションで配信される他のメッセージと同様に、トランザクションは、アプリケーションによってコミットまたはロールバックされるまで、コミットされないままになります。アプリケーションが失敗したメッセージの再配信を希望する場合は、トランザクションをロールバックする必要があります。再配信されたメッセージの JMSRedelivered メッセージヘッダーフィールドが設定され、その JMSXDeliveryCount メッセージプロパティがインクリメントされます。
        型パラメーター:
        T - メッセージ本文の型
        パラメーター:
        c - 次のメッセージの本文を割り当てる型。
        次のメッセージが TextMessage であると予想される場合は、これを String.class または String が割り当て可能な別のクラスに設定する必要があります。
        次のメッセージが ObjectMessage であると予想される場合は、これを java.io.Serializable.class または本文が割り当て可能な別のクラスに設定する必要があります。
        次のメッセージが MapMessage であると予想される場合は、これを java.util.Map.class （または java.lang.Object.class）に設定する必要があります。
        次のメッセージが BytesMessage であると予想される場合は、これを byte[].class （または java.lang.Object.class）に設定する必要があります。
        戻り値:
        この JMSConsumer に対して生成される次のメッセージの本文、またはメッセージがすぐに使用できない場合、この JMSConsumer が同時に閉じられている場合は null
        例外:
        MessageFormatRuntimeException -
        • メッセージが上記のサポートされている型のいずれでもない場合
        • メッセージ本文を指定された型に割り当てることができない場合
        • メッセージに本文がない場合
        • メッセージが ObjectMessage であり、オブジェクトの逆直列化が失敗した場合。
        JMSRuntimeException - 内部エラーが原因で Jakarta Messaging プロバイダーが次のメッセージを受信できない場合