javax.jms.MessageProducer Maven / Gradle / Ivy
/*
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS HEADER.
*
* Copyright (c) 1997-2012 Oracle and/or its affiliates. All rights reserved.
*
* The contents of this file are subject to the terms of either the GNU
* General Public License Version 2 only ("GPL") or the Common Development
* and Distribution License("CDDL") (collectively, the "License"). You
* may not use this file except in compliance with the License. You can
* obtain a copy of the License at
* https://glassfish.dev.java.net/public/CDDL+GPL_1_1.html
* or packager/legal/LICENSE.txt. See the License for the specific
* language governing permissions and limitations under the License.
*
* When distributing the software, include this License Header Notice in each
* file and include the License file at packager/legal/LICENSE.txt.
*
* GPL Classpath Exception:
* Oracle designates this particular file as subject to the "Classpath"
* exception as provided by Oracle in the GPL Version 2 section of the License
* file that accompanied this code.
*
* Modifications:
* If applicable, add the following below the License Header, with the fields
* enclosed by brackets [] replaced by your own identifying information:
* "Portions Copyright [year] [name of copyright owner]"
*
* Contributor(s):
* If you wish your version of this file to be governed by only the CDDL or
* only the GPL Version 2, indicate your decision by adding "[Contributor]
* elects to include this software in this distribution under the [CDDL or GPL
* Version 2] license." If you don't indicate a single choice of license, a
* recipient has the option to distribute your version of this file under
* either the CDDL, the GPL Version 2 or to extend the choice of license to
* its licensees as provided above. However, if you add GPL Version 2 code
* and therefore, elected the GPL Version 2 license, then the option applies
* only if the new code is made subject to such option by the copyright
* holder.
*/
package javax.jms;
/**
* 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.
*
* @version 2.0
*
* @see javax.jms.TopicPublisher
* @see javax.jms.QueueSender
* @see javax.jms.Session#createProducer
*/
public interface MessageProducer {
/**
* 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.
*
* @param value
* indicates if message IDs may be disabled
*
* @exception JMSException
* if the JMS provider fails to set message ID to disabled
* due to some internal error.
*/
void setDisableMessageID(boolean value) throws JMSException;
/**
* Gets an indication of whether message IDs are disabled.
*
* @return an indication of whether message IDs are disabled
*
* @exception JMSException
* if the JMS provider fails to determine if message IDs are
* disabled due to some internal error.
*/
boolean getDisableMessageID() 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.
*
* @param value
* indicates whether message timestamps may be disabled
*
* @exception JMSException
* if the JMS provider fails to set timestamps to disabled
* due to some internal error.
*/
void setDisableMessageTimestamp(boolean value) throws JMSException;
/**
* Gets an indication of whether message timestamps are disabled.
*
* @return an indication of whether message timestamps are disabled
*
* @exception JMSException
* if the JMS provider fails to determine if timestamps are
* disabled due to some internal error.
*/
boolean getDisableMessageTimestamp() throws JMSException;
/**
* Sets the producer's default delivery mode.
*
*
* Delivery mode is set to PERSISTENT by default.
*
* @param deliveryMode
* the message delivery mode for this message producer; legal
* values are DeliveryMode.NON_PERSISTENT and
* DeliveryMode.PERSISTENT
*
* @exception JMSException
* if the JMS provider fails to set the delivery mode due to
* some internal error.
*
* @see javax.jms.MessageProducer#getDeliveryMode
* @see javax.jms.DeliveryMode#NON_PERSISTENT
* @see javax.jms.DeliveryMode#PERSISTENT
* @see javax.jms.Message#DEFAULT_DELIVERY_MODE
*/
void setDeliveryMode(int deliveryMode) throws JMSException;
/**
* Gets the producer's default delivery mode.
*
* @return the message delivery mode for this message producer
*
* @exception JMSException
* if the JMS provider fails to get the delivery mode due to
* some internal error.
*
* @see javax.jms.MessageProducer#setDeliveryMode
*/
int getDeliveryMode() 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.
*
* @param defaultPriority
* the message priority for this message producer; must be a
* value between 0 and 9
*
*
* @exception JMSException
* if the JMS provider fails to set the priority due to some
* internal error.
*
* @see javax.jms.MessageProducer#getPriority
* @see javax.jms.Message#DEFAULT_PRIORITY
*/
void setPriority(int defaultPriority) throws JMSException;
/**
* Gets the producer's default priority.
*
* @return the message priority for this message producer
*
* @exception JMSException
* if the JMS provider fails to get the priority due to some
* internal error.
*
* @see javax.jms.MessageProducer#setPriority
*/
int getPriority() 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.
*
* @param timeToLive
* the message time to live in milliseconds; zero is unlimited
*
* @exception JMSException
* if the JMS provider fails to set the time to live due to
* some internal error.
*
* @see javax.jms.MessageProducer#getTimeToLive
* @see javax.jms.Message#DEFAULT_TIME_TO_LIVE
*/
void setTimeToLive(long timeToLive) 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.
*
* @return the message time to live in milliseconds; zero is unlimited
*
* @exception JMSException
* if the JMS provider fails to get the time to live due to
* some internal error.
*
* @see javax.jms.MessageProducer#setTimeToLive
*/
long getTimeToLive() throws JMSException;
/**
* Sets the default minimum length of time in milliseconds from its dispatch
* time before a produced message becomes visible on the target destination
* and available for delivery to consumers.
*
*
* deliveryDelay is set to zero by default.
*
* @param deliveryDelay
* the delivery delay in milliseconds.
*
* @exception JMSException
* if the JMS provider fails to set the delivery delay due to
* some internal error.
*
* @see javax.jms.MessageProducer#getDeliveryDelay
* @see javax.jms.Message#DEFAULT_DELIVERY_DELAY
*
* @since 2.0
*/
void setDeliveryDelay(long deliveryDelay) throws JMSException;
/**
* Gets the default minimum length of time in milliseconds from its dispatch
* time before a produced message becomes visible on the target destination
* and available for delivery to consumers.
*
* @return the delivery delay in milliseconds.
*
* @exception JMSException
* if the JMS provider fails to get the delivery delay due to
* some internal error.
*
* @see javax.jms.MessageProducer#setDeliveryDelay
*
* @since 2.0
*/
long getDeliveryDelay() throws JMSException;
/**
* Gets the destination associated with this MessageProducer.
*
* @return this producer's Destination
*
* @exception JMSException
* if the JMS provider fails to get the destination for this
* MessageProducer due to some internal error.
* @since 1.1
*/
Destination getDestination() 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.
*
* @exception JMSException
* if the JMS provider fails to close the producer due to
* some internal error.
*/
void close() throws JMSException;
/**
* Sends a message using the MessageProducer's default delivery
* mode, priority, and time to live.
*
* @param message
* the message to send
*
* @exception JMSException
* if the JMS provider fails to send the message due to some
* internal error.
* @exception MessageFormatException
* if an invalid message is specified.
* @exception InvalidDestinationException
* if a client uses this method with a
* MessageProducer with an invalid destination.
* @exception java.lang.UnsupportedOperationException
* if a client uses this method with a
* MessageProducer that did not specify a
* destination at creation time.
*
* @see javax.jms.Session#createProducer
*
* @since 1.1
*/
void send(Message message) throws JMSException;
/**
* Sends a message, specifying delivery mode, priority, and time to live.
*
* @param message
* the message to send
* @param deliveryMode
* the delivery mode to use
* @param priority
* the priority for this message
* @param timeToLive
* the message's lifetime (in milliseconds)
*
* @exception JMSException
* if the JMS provider fails to send the message due to some
* internal error.
* @exception MessageFormatException
* if an invalid message is specified.
* @exception InvalidDestinationException
* if a client uses this method with a
* MessageProducer with an invalid destination.
* @exception java.lang.UnsupportedOperationException
* if a client uses this method with a
* MessageProducer that did not specify a
* destination at creation time.
*
* @see javax.jms.Session#createProducer
* @since 1.1
*/
void send(Message message, int deliveryMode, int priority, long timeToLive) 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.
*
* @param destination
* the destination to send this message to
* @param message
* the message to send
*
* @exception JMSException
* if the JMS provider fails to send the message due to some
* internal error.
* @exception MessageFormatException
* if an invalid message is specified.
* @exception InvalidDestinationException
* if a client uses this method with an invalid destination.
* @exception java.lang.UnsupportedOperationException
* if a client uses this method with a
* MessageProducer that specified a destination
* at creation time.
*
* @see javax.jms.Session#createProducer
* @since 1.1
*/
void send(Destination destination, Message message) 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.
*
* @param destination
* the destination to send this message to
* @param message
* the message to send
* @param deliveryMode
* the delivery mode to use
* @param priority
* the priority for this message
* @param timeToLive
* the message's lifetime (in milliseconds)
*
* @exception JMSException
* if the JMS provider fails to send the message due to some
* internal error.
* @exception MessageFormatException
* if an invalid message is specified.
* @exception InvalidDestinationException
* if a client uses this method with an invalid destination.
*
* @see javax.jms.Session#createProducer
* @since 1.1
*/
void send(Destination destination, Message message, int deliveryMode, int priority, long timeToLive)
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 is complete, 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. The
* CompletionListener must not be invoked earlier than this.
*
* 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 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 callbacks have
* returned before performing the 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 callbacks have
* returned before closing the object and returning.
*
* Restrictions on usage in Java EE An asynchronous send is not
* permitted in a Java EE EJB or web container. If the application component
* violates this restriction this method may throw a JMSException.
*
* 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 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.
*
* An application which does not need to receive notifications when the send
* has completed or has failed may supply a null CompletionListener
* . This does not remove the requirement for the close,
* commit or rollback methods to block until any
* incomplete send operations have been completed.
*
* 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 payload 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.
*
* @param message
* the message to send
* @param completionListener
* a CompletionListener to be notified when the send
* has completed
*
* @exception JMSException
* if the JMS provider fails to send the message due to some
* internal error.
* @exception MessageFormatException
* if an invalid message is specified.
* @exception InvalidDestinationException
* if a client uses this method with a
* MessageProducer with an invalid destination.
* @exception java.lang.UnsupportedOperationException
* if a client uses this method with a
* MessageProducer that did not specify a
* destination at creation time.
*
* @see javax.jms.Session#createProducer
* @see javax.jms.CompletionListener
*
* @since 2.0
*/
void send(Message message, 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 is complete, 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. The
* CompletionListener must not be invoked earlier than this.
*
* 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 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 callbacks have
* returned before performing the 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 callbacks have
* returned before closing the object and returning.
*
* Restrictions on usage in Java EE An asynchronous send is not
* permitted in a Java EE EJB or web container. If the application component
* violates this restriction this method may throw a JMSException.
*
* 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 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.
*
* An application which does not need to receive notifications when the send
* has completed or has failed may supply a null CompletionListener
* . This does not remove the requirement for the close,
* commit or rollback methods to block until any
* incomplete send operations have been completed.
*
* 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 payload 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.
*
* @param message
* the message to send
* @param deliveryMode
* the delivery mode to use
* @param priority
* the priority for this message
* @param timeToLive
* the message's lifetime (in milliseconds)
* @param completionListener
* a CompletionListener to be notified when the send
* has completed
*
* @exception JMSException
* if the JMS provider fails to send the message due to some
* internal error.
* @exception MessageFormatException
* if an invalid message is specified.
* @exception InvalidDestinationException
* if a client uses this method with a
* MessageProducer with an invalid destination.
* @exception java.lang.UnsupportedOperationException
* if a client uses this method with a
* MessageProducer that did not specify a
* destination at creation time.
*
* @see javax.jms.Session#createProducer
* @see javax.jms.CompletionListener
* @since 2.0
*/
void send(Message message, int deliveryMode, int priority, long timeToLive, 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 is complete, 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. The
* CompletionListener must not be invoked earlier than this.
*
* 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 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 callbacks have
* returned before performing the 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 callbacks have
* returned before closing the object and returning.
*
* Restrictions on usage in Java EE An asynchronous send is not
* permitted in a Java EE EJB or web container. If the application component
* violates this restriction this method may throw a JMSException.
*
* 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 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.
*
* An application which does not need to receive notifications when the send
* has completed or has failed may supply a null CompletionListener
* . This does not remove the requirement for the close,
* commit or rollback methods to block until any
* incomplete send operations have been completed.
*
* 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 payload 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.
*
* @param destination
* the destination to send this message to
* @param message
* the message to send
* @param completionListener
* a CompletionListener to be notified when the send
* has completed
*
* @exception JMSException
* if the JMS provider fails to send the message due to some
* internal error.
* @exception MessageFormatException
* if an invalid message is specified.
* @exception InvalidDestinationException
* if a client uses this method with an invalid destination.
* @exception java.lang.UnsupportedOperationException
* if a client uses this method with a
* MessageProducer that specified a destination
* at creation time.
*
* @see javax.jms.Session#createProducer
* @see javax.jms.CompletionListener
* @since 2.0
*/
void send(Destination destination, Message message, 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 is complete, 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. The
* CompletionListener must not be invoked earlier than this.
*
* 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 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 callbacks have
* returned before performing the 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 callbacks have
* returned before closing the object and returning.
*
* Restrictions on usage in Java EE An asynchronous send is not
* permitted in a Java EE EJB or web container. If the application component
* violates this restriction this method may throw a JMSException.
*
* 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 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.
*
* An application which does not need to receive notifications when the send
* has completed or has failed may supply a null CompletionListener
* . This does not remove the requirement for the close,
* commit or rollback methods to block until any
* incomplete send operations have been completed.
*
* 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 payload 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.
*
*
* @param destination
* the destination to send this message to
* @param message
* the message to send
* @param deliveryMode
* the delivery mode to use
* @param priority
* the priority for this message
* @param timeToLive
* the message's lifetime (in milliseconds)
* @param completionListener
* a CompletionListener to be notified when the send
* has completed
*
* @exception JMSException
* if the JMS provider fails to send the message due to some
* internal error.
* @exception MessageFormatException
* if an invalid message is specified.
* @exception InvalidDestinationException
* if a client uses this method with an invalid destination.
*
* @see javax.jms.Session#createProducer
* @see javax.jms.CompletionListener
* @since 2.0
*/
void send(Destination destination, Message message, int deliveryMode, int priority, long timeToLive,
CompletionListener completionListener) throws JMSException;
}