org.apache.jmeter.protocol.jms.client

## Class ReceiveSubscriber

- java.lang.Object
- - org.apache.jmeter.protocol.jms.client.ReceiveSubscriber

- All Implemented Interfaces:
    Closeable, AutoCloseable, javax.jms.MessageListener

      public class ReceiveSubscriber
      extends Object
      implements Closeable, javax.jms.MessageListener

  Generic MessageConsumer class, which has two possible strategies.
  - Use MessageConsumer.receive(timeout) to fetch messages.
  - Use MessageListener.onMessage() to cache messages in a local queue.
  In both cases, the `getMessage(long)` method is used to return the next message, either directly using receive(timeout) or from the queue using poll(timeout).

- - ### Constructor Summary

    Constructors
    Constructor and Description
    `ReceiveSubscriber(boolean useProps, String initialContextFactory, String providerUrl, String connfactory, String destinationName, String durableSubscriptionId, String clientId, String jmsSelector, boolean useAuth, String securityPrincipal, String securityCredentials)` Constructor takes the necessary JNDI related parameters to create a connection and prepare to begin receiving messages.
    `ReceiveSubscriber(int queueSize, boolean useProps, String initialContextFactory, String providerUrl, String connfactory, String destinationName, String durableSubscriptionId, String clientId, String jmsSelector, boolean useAuth, String securityPrincipal, String securityCredentials)` Constructor takes the necessary JNDI related parameters to create a connection and create an onMessageListener to prepare to begin receiving messages.

  - ### Method Summary

    All Methods Instance Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `void` | `close()` close() will stop the connection first.
    `javax.jms.Message` | `getMessage(long timeout)` Get the next message or `null`.
    `void` | `onMessage(javax.jms.Message message)`
    `void` | `start()` Calls Connection.start() to begin receiving inbound messages.
    `void` | `stop()` Calls Connection.stop() to stop receiving inbound messages.

    - ### Methods inherited from class java.lang.Object

      `clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

- - ### Constructor Detail

    - #### ReceiveSubscriber

          public ReceiveSubscriber(boolean useProps,
                                   String initialContextFactory,
                                   String providerUrl,
                                   String connfactory,
                                   String destinationName,
                                   String durableSubscriptionId,
                                   String clientId,
                                   String jmsSelector,
                                   boolean useAuth,
                                   String securityPrincipal,
                                   String securityCredentials)
                            throws NamingException,
                                   javax.jms.JMSException

      Constructor takes the necessary JNDI related parameters to create a connection and prepare to begin receiving messages.
      The caller must then invoke `start()` to enable message reception.
      Parameters:
        `useProps` - if `true`, use jndi.properties instead of `initialContextFactory`, `providerUrl`, `securityPrincipal`, `securityCredentials`
        `initialContextFactory` - name of the initial context factory (will be ignored if `useProps` is `true`)
        `providerUrl` - url of the provider (will be ignored if `useProps` is `true`)
        `connfactory` - name of the object factory to look up in context
        `destinationName` - name of the destination
        `durableSubscriptionId` - id for a durable subscription (if empty or `null` no durable subscription will be done)
        `clientId` - client id to use (may be empty or `null`)
        `jmsSelector` - Message Selector
        `useAuth` - flag whether auth should be used (will be ignored if `useProps` is `true`)
        `securityPrincipal` - name of the principal to use for auth (will be ignored if `useProps` is `true`)
        `securityCredentials` - credentials for the principal (will be ignored if `useProps` is `true`)
      Throws:
        `javax.jms.JMSException` - if could not create context or other problem occurred.
        `NamingException` - when lookup of context or destination fails

    - #### ReceiveSubscriber

          public ReceiveSubscriber(int queueSize,
                                   boolean useProps,
                                   String initialContextFactory,
                                   String providerUrl,
                                   String connfactory,
                                   String destinationName,
                                   String durableSubscriptionId,
                                   String clientId,
                                   String jmsSelector,
                                   boolean useAuth,
                                   String securityPrincipal,
                                   String securityCredentials)
                            throws NamingException,
                                   javax.jms.JMSException

      Constructor takes the necessary JNDI related parameters to create a connection and create an onMessageListener to prepare to begin receiving messages.
      The caller must then invoke `start()` to enable message reception.
      Parameters:
        `queueSize` - maximum queue size, where a `queueSize` <=0 means no limit
        `useProps` - if `true`, use jndi.properties instead of `initialContextFactory`, `providerUrl`, `securityPrincipal`, `securityCredentials`
        `initialContextFactory` - name of the initial context factory (will be ignored if `useProps` is `true`)
        `providerUrl` - url of the provider (will be ignored if `useProps` is `true`)
        `connfactory` - name of the object factory to look up in context
        `destinationName` - name of the destination
        `durableSubscriptionId` - id for a durable subscription (if empty or `null` no durable subscription will be done)
        `clientId` - client id to use (may be empty or `null`)
        `jmsSelector` - Message Selector
        `useAuth` - flag whether auth should be used (will be ignored if `useProps` is `true`)
        `securityPrincipal` - name of the principal to use for auth (will be ignored if `useProps` is `true`)
        `securityCredentials` - credentials for the principal (will be ignored if `useProps` is `true`)
      Throws:
        `javax.jms.JMSException` - if could not create context or other problem occurred.
        `NamingException` - when lookup of context or destination fails

  - ### Method Detail

    - #### start

          public void start()
                     throws javax.jms.JMSException

      Calls Connection.start() to begin receiving inbound messages.
      Throws:
        `javax.jms.JMSException` - when starting the context fails

    - #### stop

          public void stop()
                    throws javax.jms.JMSException

      Calls Connection.stop() to stop receiving inbound messages.
      Throws:
        `javax.jms.JMSException` - when stopping the context fails

    - #### getMessage

          public javax.jms.Message getMessage(long timeout)
                                       throws javax.jms.JMSException

      Get the next message or `null`.

      Never blocks for longer than the specified timeout.

      Parameters:
        `timeout` - in milliseconds
      Returns:
        the next message or `null`
      Throws:
        `javax.jms.JMSException` - when receiving the message fails

    - #### close

          public void close()

      close() will stop the connection first. Then it closes the subscriber, session and connection.
      Specified by:
        `close` in interface `Closeable`
      Specified by:
        `close` in interface `AutoCloseable`

    - #### onMessage

          public void onMessage(javax.jms.Message message)

      Specified by:
        `onMessage` in interface `javax.jms.MessageListener`

Copyright © 1998-2022 Apache Software Foundation. All Rights Reserved.