javax.jms

## Interface MessageProducer

- All Superinterfaces:
    AutoCloseable
  All Known Subinterfaces:
    QueueSender, TopicPublisher

      public interface MessageProducer
      extends AutoCloseable

  A client uses a `MessageProducer` object to send messages to a destination. A `MessageProducer` object is created by passing a `Destination` object to a message-producer creation method supplied by a session.

  `MessageProducer` is the parent interface for all message producers.

  A client also has the option of creating a message producer without supplying a destination. In this case, a destination must be provided with every send operation. A typical use for this kind of message producer is to send replies to requests using the request's `JMSReplyTo` destination.

  A client can specify a default delivery mode, priority, time to live and delivery delay for messages sent by a message producer. It can also specify the delivery mode, priority, and time to live for an individual message.

  A client can specify a time-to-live value in milliseconds for each message it sends. This value defines a message expiration time that is the sum of the message's time-to-live and the GMT when it is sent (for transacted sends, this is the time the client sends the message, not the time the transaction is committed).

  A JMS provider should do its best to expire messages accurately; however, the JMS API does not define the accuracy provided.

  Since:
    JMS 1.0
  See Also:
    `TopicPublisher`, `QueueSender`, `Session.createProducer(javax.jms.Destination)`

- - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `void` | `close()` Closes the message producer.
    `long` | `getDeliveryDelay()` Gets the minimum length of time in milliseconds that must elapse after a message is sent before the JMS provider may deliver the message to a consumer.
    `int` | `getDeliveryMode()` Gets the producer's default delivery mode.
    `Destination` | `getDestination()` Gets the destination associated with this `MessageProducer`.
    `boolean` | `getDisableMessageID()` Gets an indication of whether message IDs are disabled.
    `boolean` | `getDisableMessageTimestamp()` Gets an indication of whether message timestamps are disabled.
    `int` | `getPriority()` Gets the producer's default priority.
    `long` | `getTimeToLive()` Gets the default length of time in milliseconds from its dispatch time that a produced message should be retained by the message system.
    `void` | `send(Destination destination, Message message)` Sends a message to a destination for an unidentified message producer using the `MessageProducer`'s default delivery mode, priority, and time to live.
    `void` | `send(Destination destination, Message message, CompletionListener completionListener)` Sends a message to a destination for an unidentified message producer, using the `MessageProducer`'s default delivery mode, priority, and time to live, performing part of the work involved in sending the message in a separate thread and notifying the specified `CompletionListener` when the operation has completed.
    `void` | `send(Destination destination, Message message, int deliveryMode, int priority, long timeToLive)` Sends a message to a destination for an unidentified message producer, specifying delivery mode, priority and time to live.
    `void` | `send(Destination destination, Message message, int deliveryMode, int priority, long timeToLive, CompletionListener completionListener)` Sends a message to a destination for an unidentified message producer, specifying delivery mode, priority and time to live, performing part of the work involved in sending the message in a separate thread and notifying the specified `CompletionListener` when the operation has completed.
    `void` | `send(Message message)` Sends a message using the `MessageProducer`'s default delivery mode, priority, and time to live.
    `void` | `send(Message message, CompletionListener completionListener)` Sends a message using the `MessageProducer`'s default delivery mode, priority, and time to live, performing part of the work involved in sending the message in a separate thread and notifying the specified `CompletionListener` when the operation has completed.
    `void` | `send(Message message, int deliveryMode, int priority, long timeToLive)` Sends a message, specifying delivery mode, priority, and time to live.
    `void` | `send(Message message, int deliveryMode, int priority, long timeToLive, CompletionListener completionListener)` Sends a message, specifying delivery mode, priority and time to live, performing part of the work involved in sending the message in a separate thread and notifying the specified `CompletionListener` when the operation has completed.
    `void` | `setDeliveryDelay(long deliveryDelay)` Sets the minimum length of time in milliseconds that must elapse after a message is sent before the JMS provider may deliver the message to a consumer.
    `void` | `setDeliveryMode(int deliveryMode)` Sets the producer's default delivery mode.
    `void` | `setDisableMessageID(boolean value)` Specify whether message IDs may be disabled.
    `void` | `setDisableMessageTimestamp(boolean value)` Specify whether message timestamps may be disabled.
    `void` | `setPriority(int defaultPriority)` Sets the producer's default priority.
    `void` | `setTimeToLive(long timeToLive)` Sets the default length of time in milliseconds from its dispatch time that a produced message should be retained by the message system.

- - ### Method Detail

    - #### setDisableMessageID

          void setDisableMessageID(boolean value)
                                   throws JMSException

      Specify whether message IDs may be disabled.

      Since message IDs take some effort to create and increase a message's size, some JMS providers may be able to optimise message overhead if they are given a hint that the message ID is not used by an application. By calling this method, a JMS application enables this potential optimisation for all messages sent using this `MessageProducer`. If the JMS provider accepts this hint, these messages must have the message ID set to null; if the provider ignores the hint, the message ID must be set to its normal unique value.

      Message IDs are enabled by default.

      Parameters:
        `value` - indicates if message IDs may be disabled
      Throws:
        `JMSException` - if the JMS provider fails to set message ID to disabled due to some internal error.

    - #### getDisableMessageID

          boolean getDisableMessageID()
                                      throws JMSException

      Gets an indication of whether message IDs are disabled.
      Returns:
        an indication of whether message IDs are disabled
      Throws:
        `JMSException` - if the JMS provider fails to determine if message IDs are disabled due to some internal error.

    - #### setDisableMessageTimestamp

          void setDisableMessageTimestamp(boolean value)
                                          throws JMSException

      Specify whether message timestamps may be disabled.

      Since timestamps take some effort to create and increase a message's size, some JMS providers may be able to optimise message overhead if they are given a hint that the timestamp is not used by an application. By calling this method, a JMS application enables this potential optimisation for all messages sent using this `MessageProducer`. If the JMS provider accepts this hint, these messages must have the timestamp set to zero; if the provider ignores the hint, the timestamp must be set to its normal value.

      Message timestamps are enabled by default.

      Parameters:
        `value` - indicates whether message timestamps may be disabled
      Throws:
        `JMSException` - if the JMS provider fails to set timestamps to disabled due to some internal error.

    - #### getDisableMessageTimestamp

          boolean getDisableMessageTimestamp()
                                             throws JMSException

      Gets an indication of whether message timestamps are disabled.
      Returns:
        an indication of whether message timestamps are disabled
      Throws:
        `JMSException` - if the JMS provider fails to determine if timestamps are disabled due to some internal error.

    - #### setDeliveryMode

          void setDeliveryMode(int deliveryMode)
                               throws JMSException

      Sets the producer's default delivery mode.

      Delivery mode is set to `PERSISTENT` by default.

      Parameters:
        `deliveryMode` - the message delivery mode for this message producer; legal values are `DeliveryMode.NON_PERSISTENT` and `DeliveryMode.PERSISTENT`
      Throws:
        `JMSException` - if the JMS provider fails to set the delivery mode due to some internal error.
      See Also:
        `getDeliveryMode()`, `DeliveryMode.NON_PERSISTENT`, `DeliveryMode.PERSISTENT`, `Message.DEFAULT_DELIVERY_MODE`

    - #### getDeliveryMode

          int getDeliveryMode()
                              throws JMSException

      Gets the producer's default delivery mode.
      Returns:
        the message delivery mode for this message producer
      Throws:
        `JMSException` - if the JMS provider fails to get the delivery mode due to some internal error.
      See Also:
        `setDeliveryMode(int)`

    - #### setPriority

          void setPriority(int defaultPriority)
                           throws JMSException

      Sets the producer's default priority.

      The JMS API defines ten levels of priority value, with 0 as the lowest priority and 9 as the highest. Clients should consider priorities 0-4 as gradations of normal priority and priorities 5-9 as gradations of expedited priority. Priority is set to 4 by default.

      Parameters:
        `defaultPriority` - the message priority for this message producer; must be a value between 0 and 9
      Throws:
        `JMSException` - if the JMS provider fails to set the priority due to some internal error.
      See Also:
        `getPriority()`, `Message.DEFAULT_PRIORITY`

    - #### getPriority

          int getPriority()
                          throws JMSException

      Gets the producer's default priority.
      Returns:
        the message priority for this message producer
      Throws:
        `JMSException` - if the JMS provider fails to get the priority due to some internal error.
      See Also:
        `setPriority(int)`

    - #### setTimeToLive

          void setTimeToLive(long timeToLive)
                             throws JMSException

      Sets the default length of time in milliseconds from its dispatch time that a produced message should be retained by the message system.

      Time to live is set to zero by default.

      Parameters:
        `timeToLive` - the message time to live in milliseconds; zero is unlimited
      Throws:
        `JMSException` - if the JMS provider fails to set the time to live due to some internal error.
      See Also:
        `getTimeToLive()`, `Message.DEFAULT_TIME_TO_LIVE`

    - #### getTimeToLive

          long getTimeToLive()
                             throws JMSException

      Gets the default length of time in milliseconds from its dispatch time that a produced message should be retained by the message system.
      Returns:
        the message time to live in milliseconds; zero is unlimited
      Throws:
        `JMSException` - if the JMS provider fails to get the time to live due to some internal error.
      See Also:
        `setTimeToLive(long)`

    - #### setDeliveryDelay

          void setDeliveryDelay(long deliveryDelay)
                                throws JMSException

      Sets the minimum length of time in milliseconds that must elapse after a message is sent before the JMS provider may deliver the message to a consumer.

      For transacted sends, this time starts when the client sends the message, not when the transaction is committed.

      deliveryDelay is set to zero by default.

      Parameters:
        `deliveryDelay` - the delivery delay in milliseconds.
      Throws:
        `JMSException` - if the JMS provider fails to set the delivery delay due to some internal error.
      Since:
        JMS 2.0
      See Also:
        `getDeliveryDelay()`, `Message.DEFAULT_DELIVERY_DELAY`

    - #### getDeliveryDelay

          long getDeliveryDelay()
                                throws JMSException

      Gets the minimum length of time in milliseconds that must elapse after a message is sent before the JMS provider may deliver the message to a consumer.
      Returns:
        the delivery delay in milliseconds.
      Throws:
        `JMSException` - if the JMS provider fails to get the delivery delay due to some internal error.
      Since:
        JMS 2.0
      See Also:
        `setDeliveryDelay(long)`

    - #### getDestination

          Destination getDestination()
                                     throws JMSException

      Gets the destination associated with this `MessageProducer`.
      Returns:
        this producer's `Destination`
      Throws:
        `JMSException` - if the JMS provider fails to get the destination for this `MessageProducer` due to some internal error.
      Since:
        JMS 1.1

    - #### close

          void close()
                     throws JMSException

      Closes the message producer.

      Since a provider may allocate some resources on behalf of a `MessageProducer` outside the Java virtual machine, clients should close them when they are not needed. Relying on garbage collection to eventually reclaim these resources may not be timely enough.

      This method must not return until any incomplete asynchronous send operations for this `MessageProducer` have been completed and any `CompletionListener` callbacks have returned. Incomplete sends should be allowed to complete normally unless an error occurs.

      A `CompletionListener` callback method must not call `close` on its own `MessageProducer`. Doing so will cause an `IllegalStateException` to be thrown.

      Specified by:
        `close` in interface `AutoCloseable`
      Throws:
        `IllegalStateException` - this method has been called by a `CompletionListener` callback method on its own `MessageProducer`
        `JMSException` - if the JMS provider fails to close the producer due to some internal error.

    - #### send

          void send(Message message)
                    throws JMSException

      Sends a message using the `MessageProducer`'s default delivery mode, priority, and time to live.
      Parameters:
        `message` - the message to send
      Throws:
        `JMSException` - if the JMS provider fails to send the message due to some internal error.
        `MessageFormatException` - if an invalid message is specified.
        `InvalidDestinationException` - if a client uses this method with a `MessageProducer` with an invalid destination.
        `UnsupportedOperationException` - if a client uses this method with a `MessageProducer` that did not specify a destination at creation time.
      Since:
        JMS 1.1
      See Also:
        `Session.createProducer(javax.jms.Destination)`

    - #### send

          void send(Message message,
                  int deliveryMode,
                  int priority,
                  long timeToLive)
                    throws JMSException

      Sends a message, specifying delivery mode, priority, and time to live.
      Parameters:
        `message` - the message to send
        `deliveryMode` - the delivery mode to use
        `priority` - the priority for this message
        `timeToLive` - the message's lifetime (in milliseconds)
      Throws:
        `JMSException` - if the JMS provider fails to send the message due to some internal error.
        `MessageFormatException` - if an invalid message is specified.
        `InvalidDestinationException` - if a client uses this method with a `MessageProducer` with an invalid destination.
        `UnsupportedOperationException` - if a client uses this method with a `MessageProducer` that did not specify a destination at creation time.
      Since:
        JMS 1.1
      See Also:
        `Session.createProducer(javax.jms.Destination)`

    - #### send

          void send(Destination destination,
                  Message message)
                    throws JMSException

      Sends a message to a destination for an unidentified message producer using the `MessageProducer`'s default delivery mode, priority, and time to live.

      Typically, a message producer is assigned a destination at creation time; however, the JMS API also supports unidentified message producers, which require that the destination be supplied every time a message is sent.

      Parameters:
        `destination` - the destination to send this message to
        `message` - the message to send
      Throws:
        `JMSException` - if the JMS provider fails to send the message due to some internal error.
        `MessageFormatException` - if an invalid message is specified.
        `InvalidDestinationException` - if a client uses this method with an invalid destination.
        `UnsupportedOperationException` - if a client uses this method with a `MessageProducer` that specified a destination at creation time.
      Since:
        JMS 1.1
      See Also:
        `Session.createProducer(javax.jms.Destination)`

    - #### send

          void send(Destination destination,
                  Message message,
                  int deliveryMode,
                  int priority,
                  long timeToLive)
                    throws JMSException

      Sends a message to a destination for an unidentified message producer, specifying delivery mode, priority and time to live.

      Typically, a message producer is assigned a destination at creation time; however, the JMS API also supports unidentified message producers, which require that the destination be supplied every time a message is sent.

      Parameters:
        `destination` - the destination to send this message to
        `message` - the message to send
        `deliveryMode` - the delivery mode to use
        `priority` - the priority for this message
        `timeToLive` - the message's lifetime (in milliseconds)
      Throws:
        `JMSException` - if the JMS provider fails to send the message due to some internal error.
        `MessageFormatException` - if an invalid message is specified.
        `InvalidDestinationException` - if a client uses this method with an invalid destination.
        `UnsupportedOperationException` - if a client uses this method with a `MessageProducer` that specified a destination at creation time.
      Since:
        JMS 1.1
      See Also:
        `Session.createProducer(javax.jms.Destination)`

    - #### send

          void send(Message message,
                  CompletionListener completionListener)
                    throws JMSException

      Sends a message using the `MessageProducer`'s default delivery mode, priority, and time to live, performing part of the work involved in sending the message in a separate thread and notifying the specified `CompletionListener` when the operation has completed. JMS refers to this as an "asynchronous send".

      When the message has been successfully sent the JMS provider invokes the callback method `onCompletion` on an application-specified `CompletionListener` object. Only when that callback has been invoked can the application be sure that the message has been successfully sent with the same degree of confidence as if a normal synchronous send had been performed. An application which requires this degree of confidence must therefore wait for the callback to be invoked before continuing.

      The following information is intended to give an indication of how an asynchronous send would typically be implemented.

      In some JMS providers, a normal synchronous send involves sending the message to a remote JMS server and then waiting for an acknowledgement to be received before returning. It is expected that such a provider would implement an asynchronous send by sending the message to the remote JMS server and then returning without waiting for an acknowledgement. When the acknowledgement is received, the JMS provider would notify the application by invoking the `onCompletion` method on the application-specified `CompletionListener` object. If for some reason the acknowledgement is not received the JMS provider would notify the application by invoking the `CompletionListener`'s `onException` method.

      In those cases where the JMS specification permits a lower level of reliability, a normal synchronous send might not wait for an acknowledgement. In that case it is expected that an asynchronous send would be similar to a synchronous send: the JMS provider would send the message to the remote JMS server and then return without waiting for an acknowledgement. However the JMS provider would still notify the application that the send had completed by invoking the `onCompletion` method on the application-specified `CompletionListener` object.

      It is up to the JMS provider to decide exactly what is performed in the calling thread and what, if anything, is performed asynchronously, so long as it satisfies the requirements given below:

      Quality of service: After the send operation has completed successfully, which means that the message has been successfully sent with the same degree of confidence as if a normal synchronous send had been performed, the JMS provider must invoke the `CompletionListener`'s `onCompletion` method. The `CompletionListener` must not be invoked earlier than this.

      Exceptions: If an exception is encountered during the call to the `send` method then an appropriate exception should be thrown in the thread that is calling the `send` method. In this case the JMS provider must not invoke the `CompletionListener`'s `onCompletion` or `onException` method. If an exception is encountered which cannot be thrown in the thread that is calling the `send` method then the JMS provider must call the `CompletionListener`'s `onException` method. In both cases if an exception occurs it is undefined whether or not the message was successfully sent.

      Message order: If the same `MessageProducer` is used to send multiple messages then JMS message ordering requirements must be satisfied. This applies even if a combination of synchronous and asynchronous sends has been performed. The application is not required to wait for an asynchronous send to complete before sending the next message.

      Close, commit or rollback: If the `close` method is called on the `MessageProducer` or its `Session` or `Connection` then the JMS provider must block until any incomplete send operations have been completed and all `CompletionListener` callbacks have returned before closing the object and returning. If the session is transacted (uses a local transaction) then when the `Session`'s `commit` or `rollback` method is called the JMS provider must block until any incomplete send operations have been completed and all `CompletionListener` callbacks have returned before performing the commit or rollback. Incomplete sends should be allowed to complete normally unless an error occurs.

      A `CompletionListener` callback method must not call `close` on its own `Connection`, `Session` or `MessageProducer` or call `commit` or `rollback` on its own `Session`. Doing so will cause the `close`, `commit` or `rollback` to throw an `IllegalStateException`.

      Restrictions on usage in Java EE This method must not be used in a Java EE EJB or web container. Doing so may cause a `JMSException` to be thrown though this is not guaranteed.

      Message headers JMS defines a number of message header fields and message properties which must be set by the "JMS provider on send". If the send is asynchronous these fields and properties may be accessed on the sending client only after the `CompletionListener` has been invoked. If the `CompletionListener`'s `onException` method is called then the state of these message header fields and properties is undefined.

      Restrictions on threading: Applications that perform an asynchronous send must confirm to the threading restrictions defined in JMS. This means that the session may be used by only one thread at a time.

      Setting a `CompletionListener` does not cause the session to be dedicated to the thread of control which calls the `CompletionListener`. The application thread may therefore continue to use the session after performing an asynchronous send. However the `CompletionListener`'s callback methods must not use the session if an application thread might be using the session at the same time.

      Use of the `CompletionListener` by the JMS provider: A session will only invoke one `CompletionListener` callback method at a time. For a given `MessageProducer`, callbacks (both `onCompletion` and `onException`) will be performed in the same order as the corresponding calls to the asynchronous send method. A JMS provider must not invoke the `CompletionListener` from the thread that is calling the asynchronous `send` method.

      Restrictions on the use of the Message object: Applications which perform an asynchronous send must take account of the restriction that a `Message` object is designed to be accessed by one logical thread of control at a time and does not support concurrent use.

      After the `send` method has returned, the application must not attempt to read the headers, properties or body of the `Message` object until the `CompletionListener`'s `onCompletion` or `onException` method has been called. This is because the JMS provider may be modifying the `Message` object in another thread during this time. The JMS provider may throw an `JMSException` if the application attempts to access or modify the `Message` object after the `send` method has returned and before the `CompletionListener` has been invoked. If the JMS provider does not throw an exception then the behaviour is undefined.

      Parameters:
        `message` - the message to send
        `completionListener` - a `CompletionListener` to be notified when the send has completed
      Throws:
        `JMSException` - if an internal error occurs
        `MessageFormatException` - if an invalid message is specified.
        `InvalidDestinationException` - if a client uses this method with a `MessageProducer` with an invalid destination.
        `IllegalArgumentException` - if the specified `CompletionListener` is null
        `UnsupportedOperationException` - if a client uses this method with a `MessageProducer` that did not specify a destination at creation time.
      Since:
        JMS 2.0
      See Also:
        `Session.createProducer(javax.jms.Destination)`, `CompletionListener`

    - #### send

          void send(Message message,
                  int deliveryMode,
                  int priority,
                  long timeToLive,
                  CompletionListener completionListener)
                    throws JMSException

      Sends a message, specifying delivery mode, priority and time to live, performing part of the work involved in sending the message in a separate thread and notifying the specified `CompletionListener` when the operation has completed. JMS refers to this as an "asynchronous send".

      When the message has been successfully sent the JMS provider invokes the callback method `onCompletion` on an application-specified `CompletionListener` object. Only when that callback has been invoked can the application be sure that the message has been successfully sent with the same degree of confidence as if a normal synchronous send had been performed. An application which requires this degree of confidence must therefore wait for the callback to be invoked before continuing.

      The following information is intended to give an indication of how an asynchronous send would typically be implemented.

      In some JMS providers, a normal synchronous send involves sending the message to a remote JMS server and then waiting for an acknowledgement to be received before returning. It is expected that such a provider would implement an asynchronous send by sending the message to the remote JMS server and then returning without waiting for an acknowledgement. When the acknowledgement is received, the JMS provider would notify the application by invoking the `onCompletion` method on the application-specified `CompletionListener` object. If for some reason the acknowledgement is not received the JMS provider would notify the application by invoking the `CompletionListener`'s `onException` method.

      In those cases where the JMS specification permits a lower level of reliability, a normal synchronous send might not wait for an acknowledgement. In that case it is expected that an asynchronous send would be similar to a synchronous send: the JMS provider would send the message to the remote JMS server and then return without waiting for an acknowledgement. However the JMS provider would still notify the application that the send had completed by invoking the `onCompletion` method on the application-specified `CompletionListener` object.

      It is up to the JMS provider to decide exactly what is performed in the calling thread and what, if anything, is performed asynchronously, so long as it satisfies the requirements given below:

      Quality of service: After the send operation has completed successfully, which means that the message has been successfully sent with the same degree of confidence as if a normal synchronous send had been performed, the JMS provider must invoke the `CompletionListener`'s `onCompletion` method. The `CompletionListener` must not be invoked earlier than this.

      Exceptions: If an exception is encountered during the call to the `send` method then an appropriate exception should be thrown in the thread that is calling the `send` method. In this case the JMS provider must not invoke the `CompletionListener`'s `onCompletion` or `onException` method. If an exception is encountered which cannot be thrown in the thread that is calling the `send` method then the JMS provider must call the `CompletionListener`'s `onException` method. In both cases if an exception occurs it is undefined whether or not the message was successfully sent.

      Message order: If the same `MessageProducer` is used to send multiple messages then JMS message ordering requirements must be satisfied. This applies even if a combination of synchronous and asynchronous sends has been performed. The application is not required to wait for an asynchronous send to complete before sending the next message.

      Close, commit or rollback: If the `close` method is called on the `MessageProducer` or its `Session` or `Connection` then the JMS provider must block until any incomplete send operations have been completed and all `CompletionListener` callbacks have returned before closing the object and returning. If the session is transacted (uses a local transaction) then when the `Session`'s `commit` or `rollback` method is called the JMS provider must block until any incomplete send operations have been completed and all `CompletionListener` callbacks have returned before performing the commit or rollback. Incomplete sends should be allowed to complete normally unless an error occurs.

      A `CompletionListener` callback method must not call `close` on its own `Connection`, `Session` or `MessageProducer` or call `commit` or `rollback` on its own `Session`. Doing so will cause the `close`, `commit` or `rollback` to throw an `IllegalStateException`.

      Restrictions on usage in Java EE This method must not be used in a Java EE EJB or web container. Doing so may cause a `JMSException` to be thrown though this is not guaranteed.

      Message headers JMS defines a number of message header fields and message properties which must be set by the "JMS provider on send". If the send is asynchronous these fields and properties may be accessed on the sending client only after the `CompletionListener` has been invoked. If the `CompletionListener`'s `onException` method is called then the state of these message header fields and properties is undefined.

      Restrictions on threading: Applications that perform an asynchronous send must confirm to the threading restrictions defined in JMS. This means that the session may be used by only one thread at a time.

      Setting a `CompletionListener` does not cause the session to be dedicated to the thread of control which calls the `CompletionListener`. The application thread may therefore continue to use the session after performing an asynchronous send. However the `CompletionListener`'s callback methods must not use the session if an application thread might be using the session at the same time.

      Use of the `CompletionListener` by the JMS provider: A session will only invoke one `CompletionListener` callback method at a time. For a given `MessageProducer`, callbacks (both `onCompletion` and `onException`) will be performed in the same order as the corresponding calls to the asynchronous send method. A JMS provider must not invoke the `CompletionListener` from the thread that is calling the asynchronous `send` method.

      Restrictions on the use of the Message object: Applications which perform an asynchronous send must take account of the restriction that a `Message` object is designed to be accessed by one logical thread of control at a time and does not support concurrent use.

      After the `send` method has returned, the application must not attempt to read the headers, properties or body of the `Message` object until the `CompletionListener`'s `onCompletion` or `onException` method has been called. This is because the JMS provider may be modifying the `Message` object in another thread during this time. The JMS provider may throw an `JMSException` if the application attempts to access or modify the `Message` object after the `send` method has returned and before the `CompletionListener` has been invoked. If the JMS provider does not throw an exception then the behaviour is undefined.

      Parameters:
        `message` - the message to send
        `deliveryMode` - the delivery mode to use
        `priority` - the priority for this message
        `timeToLive` - the message's lifetime (in milliseconds)
        `completionListener` - a `CompletionListener` to be notified when the send has completed
      Throws:
        `JMSException` - if an internal error occurs
        `MessageFormatException` - if an invalid message is specified.
        `InvalidDestinationException` - if a client uses this method with a `MessageProducer` with an invalid destination.
        `IllegalArgumentException` - if the specified `CompletionListener` is null
        `UnsupportedOperationException` - if a client uses this method with a `MessageProducer` that did not specify a destination at creation time.
      Since:
        JMS 2.0
      See Also:
        `Session.createProducer(javax.jms.Destination)`, `CompletionListener`

    - #### send

          void send(Destination destination,
                  Message message,
                  CompletionListener completionListener)
                    throws JMSException

      Sends a message to a destination for an unidentified message producer, using the `MessageProducer`'s default delivery mode, priority, and time to live, performing part of the work involved in sending the message in a separate thread and notifying the specified `CompletionListener` when the operation has completed. JMS refers to this as an "asynchronous send".

      Typically, a message producer is assigned a destination at creation time; however, the JMS API also supports unidentified message producers, which require that the destination be supplied every time a message is sent.

      When the message has been successfully sent the JMS provider invokes the callback method `onCompletion` on an application-specified `CompletionListener` object. Only when that callback has been invoked can the application be sure that the message has been successfully sent with the same degree of confidence as if a normal synchronous send had been performed. An application which requires this degree of confidence must therefore wait for the callback to be invoked before continuing.

      The following information is intended to give an indication of how an asynchronous send would typically be implemented.

      In some JMS providers, a normal synchronous send involves sending the message to a remote JMS server and then waiting for an acknowledgement to be received before returning. It is expected that such a provider would implement an asynchronous send by sending the message to the remote JMS server and then returning without waiting for an acknowledgement. When the acknowledgement is received, the JMS provider would notify the application by invoking the `onCompletion` method on the application-specified `CompletionListener` object. If for some reason the acknowledgement is not received the JMS provider would notify the application by invoking the `CompletionListener`'s `onException` method.

      In those cases where the JMS specification permits a lower level of reliability, a normal synchronous send might not wait for an acknowledgement. In that case it is expected that an asynchronous send would be similar to a synchronous send: the JMS provider would send the message to the remote JMS server and then return without waiting for an acknowledgement. However the JMS provider would still notify the application that the send had completed by invoking the `onCompletion` method on the application-specified `CompletionListener` object.

      It is up to the JMS provider to decide exactly what is performed in the calling thread and what, if anything, is performed asynchronously, so long as it satisfies the requirements given below:

      Quality of service: After the send operation has completed successfully, which means that the message has been successfully sent with the same degree of confidence as if a normal synchronous send had been performed, the JMS provider must invoke the `CompletionListener`'s `onCompletion` method. The `CompletionListener` must not be invoked earlier than this.

      Exceptions: If an exception is encountered during the call to the `send` method then an appropriate exception should be thrown in the thread that is calling the `send` method. In this case the JMS provider must not invoke the `CompletionListener`'s `onCompletion` or `onException` method. If an exception is encountered which cannot be thrown in the thread that is calling the `send` method then the JMS provider must call the `CompletionListener`'s `onException` method. In both cases if an exception occurs it is undefined whether or not the message was successfully sent.

      Message order: If the same `MessageProducer` is used to send multiple messages then JMS message ordering requirements must be satisfied. This applies even if a combination of synchronous and asynchronous sends has been performed. The application is not required to wait for an asynchronous send to complete before sending the next message.

      Close, commit or rollback: If the `close` method is called on the `MessageProducer` or its `Session` or `Connection` then the JMS provider must block until any incomplete send operations have been completed and all `CompletionListener` callbacks have returned before closing the object and returning. If the session is transacted (uses a local transaction) then when the `Session`'s `commit` or `rollback` method is called the JMS provider must block until any incomplete send operations have been completed and all `CompletionListener` callbacks have returned before performing the commit or rollback. Incomplete sends should be allowed to complete normally unless an error occurs.

      A `CompletionListener` callback method must not call `close` on its own `Connection`, `Session` or `MessageProducer` or call `commit` or `rollback` on its own `Session`. Doing so will cause the `close`, `commit` or `rollback` to throw an `IllegalStateException`.

      Restrictions on usage in Java EE This method must not be used in a Java EE EJB or web container. Doing so may cause a `JMSException` to be thrown though this is not guaranteed.

      Message headers JMS defines a number of message header fields and message properties which must be set by the "JMS provider on send". If the send is asynchronous these fields and properties may be accessed on the sending client only after the `CompletionListener` has been invoked. If the `CompletionListener`'s `onException` method is called then the state of these message header fields and properties is undefined.

      Restrictions on threading: Applications that perform an asynchronous send must confirm to the threading restrictions defined in JMS. This means that the session may be used by only one thread at a time.

      Setting a `CompletionListener` does not cause the session to be dedicated to the thread of control which calls the `CompletionListener`. The application thread may therefore continue to use the session after performing an asynchronous send. However the `CompletionListener`'s callback methods must not use the session if an application thread might be using the session at the same time.

      Use of the `CompletionListener` by the JMS provider: A session will only invoke one `CompletionListener` callback method at a time. For a given `MessageProducer`, callbacks (both `onCompletion` and `onException`) will be performed in the same order as the corresponding calls to the asynchronous send method. A JMS provider must not invoke the `CompletionListener` from the thread that is calling the asynchronous `send` method.

      Restrictions on the use of the Message object: Applications which perform an asynchronous send must take account of the restriction that a `Message` object is designed to be accessed by one logical thread of control at a time and does not support concurrent use.

      After the `send` method has returned, the application must not attempt to read the headers, properties or body of the `Message` object until the `CompletionListener`'s `onCompletion` or `onException` method has been called. This is because the JMS provider may be modifying the `Message` object in another thread during this time. The JMS provider may throw an `JMSException` if the application attempts to access or modify the `Message` object after the `send` method has returned and before the `CompletionListener` has been invoked. If the JMS provider does not throw an exception then the behaviour is undefined.

      Parameters:
        `destination` - the destination to send this message to
        `message` - the message to send
        `completionListener` - a `CompletionListener` to be notified when the send has completed
      Throws:
        `JMSException` - if an internal error occurs
        `MessageFormatException` - if an invalid message is specified.
        `InvalidDestinationException` - if a client uses this method with an invalid destination
        `IllegalArgumentException` - if the specified `CompletionListener` is null
        `UnsupportedOperationException` - if a client uses this method with a `MessageProducer` that specified a destination at creation time.
      Since:
        JMS 2.0
      See Also:
        `Session.createProducer(javax.jms.Destination)`, `CompletionListener`

    - #### send

          void send(Destination destination,
                  Message message,
                  int deliveryMode,
                  int priority,
                  long timeToLive,
                  CompletionListener completionListener)
                    throws JMSException

      Sends a message to a destination for an unidentified message producer, specifying delivery mode, priority and time to live, performing part of the work involved in sending the message in a separate thread and notifying the specified `CompletionListener` when the operation has completed. JMS refers to this as an "asynchronous send".

      Typically, a message producer is assigned a destination at creation time; however, the JMS API also supports unidentified message producers, which require that the destination be supplied every time a message is sent.

      When the message has been successfully sent the JMS provider invokes the callback method `onCompletion` on an application-specified `CompletionListener` object. Only when that callback has been invoked can the application be sure that the message has been successfully sent with the same degree of confidence as if a normal synchronous send had been performed. An application which requires this degree of confidence must therefore wait for the callback to be invoked before continuing.

      The following information is intended to give an indication of how an asynchronous send would typically be implemented.

      In some JMS providers, a normal synchronous send involves sending the message to a remote JMS server and then waiting for an acknowledgement to be received before returning. It is expected that such a provider would implement an asynchronous send by sending the message to the remote JMS server and then returning without waiting for an acknowledgement. When the acknowledgement is received, the JMS provider would notify the application by invoking the `onCompletion` method on the application-specified `CompletionListener` object. If for some reason the acknowledgement is not received the JMS provider would notify the application by invoking the `CompletionListener`'s `onException` method.

      In those cases where the JMS specification permits a lower level of reliability, a normal synchronous send might not wait for an acknowledgement. In that case it is expected that an asynchronous send would be similar to a synchronous send: the JMS provider would send the message to the remote JMS server and then return without waiting for an acknowledgement. However the JMS provider would still notify the application that the send had completed by invoking the `onCompletion` method on the application-specified `CompletionListener` object.

      It is up to the JMS provider to decide exactly what is performed in the calling thread and what, if anything, is performed asynchronously, so long as it satisfies the requirements given below:

      Quality of service: After the send operation has completed successfully, which means that the message has been successfully sent with the same degree of confidence as if a normal synchronous send had been performed, the JMS provider must invoke the `CompletionListener`'s `onCompletion` method. The `CompletionListener` must not be invoked earlier than this.

      Exceptions: If an exception is encountered during the call to the `send` method then an appropriate exception should be thrown in the thread that is calling the `send` method. In this case the JMS provider must not invoke the `CompletionListener`'s `onCompletion` or `onException` method. If an exception is encountered which cannot be thrown in the thread that is calling the `send` method then the JMS provider must call the `CompletionListener`'s `onException` method. In both cases if an exception occurs it is undefined whether or not the message was successfully sent.

      Message order: If the same `MessageProducer` is used to send multiple messages then JMS message ordering requirements must be satisfied. This applies even if a combination of synchronous and asynchronous sends has been performed. The application is not required to wait for an asynchronous send to complete before sending the next message.

      Close, commit or rollback: If the `close` method is called on the `MessageProducer` or its `Session` or `Connection` then the JMS provider must block until any incomplete send operations have been completed and all `CompletionListener` callbacks have returned before closing the object and returning. If the session is transacted (uses a local transaction) then when the `Session`'s `commit` or `rollback` method is called the JMS provider must block until any incomplete send operations have been completed and all `CompletionListener` callbacks have returned before performing the commit or rollback. Incomplete sends should be allowed to complete normally unless an error occurs.

      A `CompletionListener` callback method must not call `close` on its own `Connection`, `Session` or `MessageProducer` or call `commit` or `rollback` on its own `Session`. Doing so will cause the `close`, `commit` or `rollback` to throw an `IllegalStateException`.

      Restrictions on usage in Java EE This method must not be used in a Java EE EJB or web container. Doing so may cause a `JMSException` to be thrown though this is not guaranteed.

      Message headers JMS defines a number of message header fields and message properties which must be set by the "JMS provider on send". If the send is asynchronous these fields and properties may be accessed on the sending client only after the `CompletionListener` has been invoked. If the `CompletionListener`'s `onException` method is called then the state of these message header fields and properties is undefined.

      Restrictions on threading: Applications that perform an asynchronous send must confirm to the threading restrictions defined in JMS. This means that the session may be used by only one thread at a time.

      Setting a `CompletionListener` does not cause the session to be dedicated to the thread of control which calls the `CompletionListener`. The application thread may therefore continue to use the session after performing an asynchronous send. However the `CompletionListener`'s callback methods must not use the session if an application thread might be using the session at the same time.

      Use of the `CompletionListener` by the JMS provider: A session will only invoke one `CompletionListener` callback method at a time. For a given `MessageProducer`, callbacks (both `onCompletion` and `onException`) will be performed in the same order as the corresponding calls to the asynchronous send method. A JMS provider must not invoke the `CompletionListener` from the thread that is calling the asynchronous `send` method.

      Restrictions on the use of the Message object: Applications which perform an asynchronous send must take account of the restriction that a `Message` object is designed to be accessed by one logical thread of control at a time and does not support concurrent use.

      After the `send` method has returned, the application must not attempt to read the headers, properties or body of the `Message` object until the `CompletionListener`'s `onCompletion` or `onException` method has been called. This is because the JMS provider may be modifying the `Message` object in another thread during this time. The JMS provider may throw an `JMSException` if the application attempts to access or modify the `Message` object after the `send` method has returned and before the `CompletionListener` has been invoked. If the JMS provider does not throw an exception then the behaviour is undefined.

      Parameters:
        `destination` - the destination to send this message to
        `message` - the message to send
        `deliveryMode` - the delivery mode to use
        `priority` - the priority for this message
        `timeToLive` - the message's lifetime (in milliseconds)
        `completionListener` - a `CompletionListener` to be notified when the send has completed
      Throws:
        `JMSException` - if an internal error occurs
        `MessageFormatException` - if an invalid message is specified.
        `InvalidDestinationException` - if a client uses this method with an invalid destination.
        `IllegalArgumentException` - if the specified `CompletionListener` is null
        `UnsupportedOperationException` - if a client uses this method with a `MessageProducer` that specified a destination at creation time.
      Since:
        JMS 2.0
      See Also:
        `Session.createProducer(javax.jms.Destination)`, `CompletionListener`

Copyright (c) 2013, Oracle and/or its affiliates. All rights reserved.