Java tutorial
/* * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS HEADER. * * Copyright (c) 1997-2013 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 {@code MessageProducer} object to send messages to a * destination. A {@code MessageProducer} object is created by passing a * {@code Destination} object to a message-producer creation method * supplied by a session. * * <P> * {@code MessageProducer} is the parent interface for all message * producers. * * <P> * 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 {@code JMSReplyTo} destination. * * <P> * 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. * * <P> * 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). * * <P> * A JMS provider should do its best to expire messages accurately; however, the * JMS API does not define the accuracy provided. * @see javax.jms.TopicPublisher * @see javax.jms.QueueSender * @see javax.jms.Session#createProducer * * @version JMS 2.0 * @since JMS 1.0 * */ public interface MessageProducer extends AutoCloseable { /** * Specify whether message IDs may be disabled. * <p> * 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 {@code 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. * <p> * 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. * <p> * 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 {@code 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. * <p> * 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. * * <P> * Delivery mode is set to {@code PERSISTENT} by default. * * @param deliveryMode * the message delivery mode for this message producer; legal * values are {@code DeliveryMode.NON_PERSISTENT} and * {@code 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. * * <P> * 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. * * <P> * 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 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. * <p> * For transacted sends, this time starts when the client sends the message, * not when the transaction is committed. * <p> * 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 JMS 2.0 */ void setDeliveryDelay(long deliveryDelay) 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. * * @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 JMS 2.0 */ long getDeliveryDelay() throws JMSException; /** * Gets the destination associated with this {@code MessageProducer}. * * @return this producer's {@code Destination} * * @exception JMSException * if the JMS provider fails to get the destination for this * {@code MessageProducer} due to some internal error. * * @since JMS 1.1 */ Destination getDestination() throws JMSException; /** * Closes the message producer. * * <P> * Since a provider may allocate some resources on behalf of a * {@code 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. * <p> * This method must not return until any incomplete asynchronous send * operations for this <tt>MessageProducer</tt> have been completed and any * <tt>CompletionListener</tt> callbacks have returned. Incomplete sends * should be allowed to complete normally unless an error occurs. * <p> * A <tt>CompletionListener</tt> callback method must not call * <tt>close</tt> on its own <tt>MessageProducer</tt>. Doing so will cause an * <tt>IllegalStateException</tt> to be thrown. * <p> * * @exception IllegalStateException * this method has * been called by a <tt>CompletionListener</tt> callback * method on its own <tt>MessageProducer</tt> * @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 {@code 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 * {@code MessageProducer} with an invalid destination. * @exception java.lang.UnsupportedOperationException * if a client uses this method with a * {@code MessageProducer} that did not specify a * destination at creation time. * * @see javax.jms.Session#createProducer * * @since JMS 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 * {@code MessageProducer} with an invalid destination. * @exception java.lang.UnsupportedOperationException * if a client uses this method with a * {@code MessageProducer} that did not specify a * destination at creation time. * * @see javax.jms.Session#createProducer * @since JMS 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 {@code MessageProducer}'s default delivery mode, priority, * and time to live. * * <P> * 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 * {@code MessageProducer} that specified a destination * at creation time. * * @see javax.jms.Session#createProducer * @since JMS 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. * * <P> * 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. * @exception java.lang.UnsupportedOperationException * if a client uses this method with a * {@code MessageProducer} that specified a destination * at creation time. * * @see javax.jms.Session#createProducer * @since JMS 1.1 */ void send(Destination destination, Message message, int deliveryMode, int priority, long timeToLive) throws JMSException; /** * Sends a message using the {@code 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 * <tt>CompletionListener</tt> when the operation has completed. JMS refers * to this as an "asynchronous send". * <p> * When the message has been successfully sent the JMS provider invokes the * callback method <tt>onCompletion</tt> on an application-specified * <tt>CompletionListener</tt> 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. * <p> * The following information is intended to give an indication of how an * asynchronous send would typically be implemented. * <p> * 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 <tt>onCompletion</tt> method on the * application-specified <tt>CompletionListener</tt> object. If for some * reason the acknowledgement is not received the JMS provider would notify * the application by invoking the <tt>CompletionListener</tt>'s * <tt>onException</tt> method. * <p> * 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 * <tt>onCompletion</tt> method on the application-specified * <tt>CompletionListener</tt> object. * <p> * 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: * <p> * <b>Quality of service</b>: 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 * <tt>CompletionListener</tt>'s <tt>onCompletion</tt> method. The * <tt>CompletionListener</tt> must not be invoked earlier than this. * <p> * <b>Exceptions</b>: If an exception is encountered during the call to the * <tt>send</tt> method then an appropriate exception should be thrown in * the thread that is calling the <tt>send</tt> method. In this case the JMS provider * must not invoke the <tt>CompletionListener</tt>'s <tt>onCompletion</tt> * or <tt>onException</tt> method. If an exception is encountered which * cannot be thrown in the thread that is calling the <tt>send</tt> method then the * JMS provider must call the <tt>CompletionListener</tt>'s * <tt>onException</tt> method. In both cases if an exception occurs it is * undefined whether or not the message was successfully sent. * <p> * <b>Message order</b>: If the same <tt>MessageProducer</tt> 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. * <p> * <b>Close, commit or rollback</b>: If the <tt>close</tt> method is called * on the <tt>MessageProducer</tt> or its <tt>Session</tt> or * <tt>Connection</tt> then the JMS provider must block until any incomplete * send operations have been completed and all * {@code CompletionListener} callbacks have returned before closing * the object and returning. If the session is transacted (uses a local * transaction) then when the <tt>Session</tt>'s <tt>commit</tt> or * <tt>rollback</tt> method is called the JMS provider must block until any * incomplete send operations have been completed and all * {@code CompletionListener} callbacks have returned before performing * the commit or rollback. Incomplete sends should be allowed to complete * normally unless an error occurs. * <p> * A <tt>CompletionListener</tt> callback method must not call * <tt>close</tt> on its own <tt>Connection</tt>, <tt>Session</tt> or * <tt>MessageProducer</tt> or call <tt>commit</tt> or <tt>rollback</tt> on * its own <tt>Session</tt>. Doing so will cause the <tt>close</tt>, * <tt>commit</tt> or <tt>rollback</tt> to throw an * <tt>IllegalStateException</tt>. * <p> * <b>Restrictions on usage in Java EE</b> This method must not be used in a * Java EE EJB or web container. Doing so may cause a {@code JMSException} * to be thrown though this is not guaranteed. * <p> * <b>Message headers</b> 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 <tt>CompletionListener</tt> has been * invoked. If the <tt>CompletionListener</tt>'s <tt>onException</tt> method * is called then the state of these message header fields and properties is * undefined. * <p> * <b>Restrictions on threading</b>: 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. * <p> * Setting a <tt>CompletionListener</tt> does not cause the session to be * dedicated to the thread of control which calls the * <tt>CompletionListener</tt>. The application thread may therefore * continue to use the session after performing an asynchronous send. * However the <tt>CompletionListener</tt>'s callback methods must not use * the session if an application thread might be using the session at the * same time. * <p> * <b>Use of the <tt>CompletionListener</tt> by the JMS provider</b>: A * session will only invoke one <tt>CompletionListener</tt> callback method * at a time. For a given <tt>MessageProducer</tt>, callbacks (both * {@code onCompletion} and {@code onException}) will be performed * in the same order as the corresponding calls to the asynchronous send * method. * A JMS provider must not invoke the <tt>CompletionListener</tt> from the * thread that is calling the asynchronous <tt>send</tt> method. * <p> * <b>Restrictions on the use of the Message object</b>: Applications which * perform an asynchronous send must take account of the restriction that a * <tt>Message</tt> object is designed to be accessed by one logical thread * of control at a time and does not support concurrent use. * <p> * After the <tt>send</tt> method has returned, the application must not * attempt to read the headers, properties or body of the * <tt>Message</tt> object until the <tt>CompletionListener</tt>'s * <tt>onCompletion</tt> or <tt>onException</tt> method has been called. * This is because the JMS provider may be modifying the <tt>Message</tt> * object in another thread during this time. The JMS provider may throw an * <tt>JMSException</tt> if the application attempts to access or modify the * <tt>Message</tt> object after the <tt>send</tt> method has returned and * before the <tt>CompletionListener</tt> 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 {@code CompletionListener} to be notified when the send * has completed * * @exception JMSException * if an internal error occurs * @exception MessageFormatException * if an invalid message is specified. * @exception InvalidDestinationException * if a client uses this method with a * {@code MessageProducer} with an invalid destination. * @exception java.lang.IllegalArgumentException * if the specified {@code CompletionListener} is null * @exception java.lang.UnsupportedOperationException * if a client uses this method with a * {@code MessageProducer} that did not specify a * destination at creation time. * * @see javax.jms.Session#createProducer * @see javax.jms.CompletionListener * * @since JMS 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 <tt>CompletionListener</tt> when the * operation has completed. JMS refers to this as an "asynchronous send". * <p> * When the message has been successfully sent the JMS provider invokes the * callback method <tt>onCompletion</tt> on an application-specified * <tt>CompletionListener</tt> 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. * <p> * The following information is intended to give an indication of how an * asynchronous send would typically be implemented. * <p> * 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 <tt>onCompletion</tt> method on the * application-specified <tt>CompletionListener</tt> object. If for some * reason the acknowledgement is not received the JMS provider would notify * the application by invoking the <tt>CompletionListener</tt>'s * <tt>onException</tt> method. * <p> * 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 * <tt>onCompletion</tt> method on the application-specified * <tt>CompletionListener</tt> object. * <p> * 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: * <p> * <b>Quality of service</b>: 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 * <tt>CompletionListener</tt>'s <tt>onCompletion</tt> method. The * <tt>CompletionListener</tt> must not be invoked earlier than this. * <p> * <b>Exceptions</b>: If an exception is encountered during the call to the * <tt>send</tt> method then an appropriate exception should be thrown in * the thread that is calling the <tt>send</tt> method. In this case the JMS provider * must not invoke the <tt>CompletionListener</tt>'s <tt>onCompletion</tt> * or <tt>onException</tt> method. If an exception is encountered which * cannot be thrown in the thread that is calling the <tt>send</tt> method then the * JMS provider must call the <tt>CompletionListener</tt>'s * <tt>onException</tt> method. In both cases if an exception occurs it is * undefined whether or not the message was successfully sent. * <p> * <b>Message order</b>: If the same <tt>MessageProducer</tt> 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. * <p> * <b>Close, commit or rollback</b>: If the <tt>close</tt> method is called * on the <tt>MessageProducer</tt> or its <tt>Session</tt> or * <tt>Connection</tt> then the JMS provider must block until any incomplete * send operations have been completed and all * {@code CompletionListener} callbacks have returned before closing * the object and returning. If the session is transacted (uses a local * transaction) then when the <tt>Session</tt>'s <tt>commit</tt> or * <tt>rollback</tt> method is called the JMS provider must block until any * incomplete send operations have been completed and all * {@code CompletionListener} callbacks have returned before performing * the commit or rollback. Incomplete sends should be allowed to complete * normally unless an error occurs. * <p> * A <tt>CompletionListener</tt> callback method must not call * <tt>close</tt> on its own <tt>Connection</tt>, <tt>Session</tt> or * <tt>MessageProducer</tt> or call <tt>commit</tt> or <tt>rollback</tt> on * its own <tt>Session</tt>. Doing so will cause the <tt>close</tt>, * <tt>commit</tt> or <tt>rollback</tt> to throw an * <tt>IllegalStateException</tt>. * <p> * <b>Restrictions on usage in Java EE</b> This method must not be used in a * Java EE EJB or web container. Doing so may cause a {@code JMSException} * to be thrown though this is not guaranteed. * <p> * <b>Message headers</b> 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 <tt>CompletionListener</tt> has been * invoked. If the <tt>CompletionListener</tt>'s <tt>onException</tt> method * is called then the state of these message header fields and properties is * undefined. * <p> * <b>Restrictions on threading</b>: 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. * <p> * Setting a <tt>CompletionListener</tt> does not cause the session to be * dedicated to the thread of control which calls the * <tt>CompletionListener</tt>. The application thread may therefore * continue to use the session after performing an asynchronous send. * However the <tt>CompletionListener</tt>'s callback methods must not use * the session if an application thread might be using the session at the * same time. * <p> * <b>Use of the <tt>CompletionListener</tt> by the JMS provider</b>: A * session will only invoke one <tt>CompletionListener</tt> callback method * at a time. For a given <tt>MessageProducer</tt>, callbacks (both * {@code onCompletion} and {@code onException}) will be performed * in the same order as the corresponding calls to the asynchronous send * method. * A JMS provider must not invoke the <tt>CompletionListener</tt> from the * thread that is calling the asynchronous <tt>send</tt> method. * <p> * <b>Restrictions on the use of the Message object</b>: Applications which * perform an asynchronous send must take account of the restriction that a * <tt>Message</tt> object is designed to be accessed by one logical thread * of control at a time and does not support concurrent use. * <p> * After the <tt>send</tt> method has returned, the application must not * attempt to read the headers, properties or body of the * <tt>Message</tt> object until the <tt>CompletionListener</tt>'s * <tt>onCompletion</tt> or <tt>onException</tt> method has been called. * This is because the JMS provider may be modifying the <tt>Message</tt> * object in another thread during this time. The JMS provider may throw an * <tt>JMSException</tt> if the application attempts to access or modify the * <tt>Message</tt> object after the <tt>send</tt> method has returned and * before the <tt>CompletionListener</tt> 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 {@code CompletionListener} to be notified when the send * has completed * * @exception JMSException * if an internal error occurs * @exception MessageFormatException * if an invalid message is specified. * @exception InvalidDestinationException * if a client uses this method with a * {@code MessageProducer} with an invalid destination. * @exception java.lang.IllegalArgumentException * if the specified {@code CompletionListener} is null * @exception java.lang.UnsupportedOperationException * if a client uses this method with a * {@code MessageProducer} that did not specify a * destination at creation time. * * @see javax.jms.Session#createProducer * @see javax.jms.CompletionListener * * @since JMS 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 {@code 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 * <tt>CompletionListener</tt> when the operation has completed. JMS refers * to this as an "asynchronous send". * <p> * 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. * <p> * When the message has been successfully sent the JMS provider invokes the * callback method <tt>onCompletion</tt> on an application-specified * <tt>CompletionListener</tt> 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. * <p> * The following information is intended to give an indication of how an * asynchronous send would typically be implemented. * <p> * 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 <tt>onCompletion</tt> method on the * application-specified <tt>CompletionListener</tt> object. If for some * reason the acknowledgement is not received the JMS provider would notify * the application by invoking the <tt>CompletionListener</tt>'s * <tt>onException</tt> method. * <p> * 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 * <tt>onCompletion</tt> method on the application-specified * <tt>CompletionListener</tt> object. * <p> * 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: * <p> * <b>Quality of service</b>: 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 * <tt>CompletionListener</tt>'s <tt>onCompletion</tt> method. The * <tt>CompletionListener</tt> must not be invoked earlier than this. * <p> * <b>Exceptions</b>: If an exception is encountered during the call to the * <tt>send</tt> method then an appropriate exception should be thrown in * the thread that is calling the <tt>send</tt> method. In this case the JMS * provider must not invoke the <tt>CompletionListener</tt>'s * <tt>onCompletion</tt> or <tt>onException</tt> method. If an exception is * encountered which cannot be thrown in the thread that is calling the * <tt>send</tt> method then the JMS provider must call the * <tt>CompletionListener</tt>'s <tt>onException</tt> method. In both cases * if an exception occurs it is undefined whether or not the message was * successfully sent. * <p> * <b>Message order</b>: If the same <tt>MessageProducer</tt> 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. * <p> * <b>Close, commit or rollback</b>: If the <tt>close</tt> method is called * on the <tt>MessageProducer</tt> or its <tt>Session</tt> or * <tt>Connection</tt> then the JMS provider must block until any incomplete * send operations have been completed and all * {@code CompletionListener} callbacks have returned before closing * the object and returning. If the session is transacted (uses a local * transaction) then when the <tt>Session</tt>'s <tt>commit</tt> or * <tt>rollback</tt> method is called the JMS provider must block until any * incomplete send operations have been completed and all * {@code CompletionListener} callbacks have returned before performing * the commit or rollback. Incomplete sends should be allowed to complete * normally unless an error occurs. * <p> * A <tt>CompletionListener</tt> callback method must not call * <tt>close</tt> on its own <tt>Connection</tt>, <tt>Session</tt> or * <tt>MessageProducer</tt> or call <tt>commit</tt> or <tt>rollback</tt> on * its own <tt>Session</tt>. Doing so will cause the <tt>close</tt>, * <tt>commit</tt> or <tt>rollback</tt> to throw an * <tt>IllegalStateException</tt>. * <p> * <b>Restrictions on usage in Java EE</b> This method must not be used in a * Java EE EJB or web container. Doing so may cause a {@code JMSException} * to be thrown though this is not guaranteed. * <p> * <b>Message headers</b> 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 <tt>CompletionListener</tt> has been * invoked. If the <tt>CompletionListener</tt>'s <tt>onException</tt> method * is called then the state of these message header fields and properties is * undefined. * <p> * <b>Restrictions on threading</b>: 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. * <p> * Setting a <tt>CompletionListener</tt> does not cause the session to be * dedicated to the thread of control which calls the * <tt>CompletionListener</tt>. The application thread may therefore * continue to use the session after performing an asynchronous send. * However the <tt>CompletionListener</tt>'s callback methods must not use * the session if an application thread might be using the session at the * same time. * <p> * <b>Use of the <tt>CompletionListener</tt> by the JMS provider</b>: A * session will only invoke one <tt>CompletionListener</tt> callback method * at a time. For a given <tt>MessageProducer</tt>, callbacks (both * {@code onCompletion} and {@code onException}) will be performed * in the same order as the corresponding calls to the asynchronous send * method. A JMS provider must not invoke the <tt>CompletionListener</tt> * from the thread that is calling the asynchronous <tt>send</tt> method. * <p> * <b>Restrictions on the use of the Message object</b>: Applications which * perform an asynchronous send must take account of the restriction that a * <tt>Message</tt> object is designed to be accessed by one logical thread * of control at a time and does not support concurrent use. * <p> * After the <tt>send</tt> method has returned, the application must not * attempt to read the headers, properties or body of the * <tt>Message</tt> object until the <tt>CompletionListener</tt>'s * <tt>onCompletion</tt> or <tt>onException</tt> method has been called. * This is because the JMS provider may be modifying the <tt>Message</tt> * object in another thread during this time. The JMS provider may throw an * <tt>JMSException</tt> if the application attempts to access or modify the * <tt>Message</tt> object after the <tt>send</tt> method has returned and * before the <tt>CompletionListener</tt> 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 {@code CompletionListener} to be notified when the send * has completed * * @exception JMSException * if an internal error occurs * @exception MessageFormatException * if an invalid message is specified. * @exception InvalidDestinationException * if a client uses this method with an invalid destination * @exception java.lang.IllegalArgumentException * if the specified {@code CompletionListener} is null * @exception java.lang.UnsupportedOperationException * if a client uses this method with a * {@code MessageProducer} that specified a destination * at creation time. * * @see javax.jms.Session#createProducer * @see javax.jms.CompletionListener * * @since JMS 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 <tt>CompletionListener</tt> when the operation * has completed. JMS refers to this as an "asynchronous send". * <p> * 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. * <p> * When the message has been successfully sent the JMS provider invokes the * callback method <tt>onCompletion</tt> on an application-specified * <tt>CompletionListener</tt> 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. * <p> * The following information is intended to give an indication of how an * asynchronous send would typically be implemented. * <p> * 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 <tt>onCompletion</tt> method on the * application-specified <tt>CompletionListener</tt> object. If for some * reason the acknowledgement is not received the JMS provider would notify * the application by invoking the <tt>CompletionListener</tt>'s * <tt>onException</tt> method. * <p> * 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 * <tt>onCompletion</tt> method on the application-specified * <tt>CompletionListener</tt> object. * <p> * 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: * <p> * <b>Quality of service</b>: 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 * <tt>CompletionListener</tt>'s <tt>onCompletion</tt> method. The * <tt>CompletionListener</tt> must not be invoked earlier than this. * <p> * <b>Exceptions</b>: If an exception is encountered during the call to the * <tt>send</tt> method then an appropriate exception should be thrown in * the thread that is calling the <tt>send</tt> method. In this case the JMS provider * must not invoke the <tt>CompletionListener</tt>'s <tt>onCompletion</tt> * or <tt>onException</tt> method. If an exception is encountered which * cannot be thrown in the thread that is calling the <tt>send</tt> method then the * JMS provider must call the <tt>CompletionListener</tt>'s * <tt>onException</tt> method. In both cases if an exception occurs it is * undefined whether or not the message was successfully sent. * <p> * <b>Message order</b>: If the same <tt>MessageProducer</tt> 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. * <p> * <b>Close, commit or rollback</b>: If the <tt>close</tt> method is called * on the <tt>MessageProducer</tt> or its <tt>Session</tt> or * <tt>Connection</tt> then the JMS provider must block until any incomplete * send operations have been completed and all * {@code CompletionListener} callbacks have returned before closing * the object and returning. If the session is transacted (uses a local * transaction) then when the <tt>Session</tt>'s <tt>commit</tt> or * <tt>rollback</tt> method is called the JMS provider must block until any * incomplete send operations have been completed and all * {@code CompletionListener} callbacks have returned before performing * the commit or rollback. Incomplete sends should be allowed to complete * normally unless an error occurs. * <p> * A <tt>CompletionListener</tt> callback method must not call * <tt>close</tt> on its own <tt>Connection</tt>, <tt>Session</tt> or * <tt>MessageProducer</tt> or call <tt>commit</tt> or <tt>rollback</tt> on * its own <tt>Session</tt>. Doing so will cause the <tt>close</tt>, * <tt>commit</tt> or <tt>rollback</tt> to throw an * <tt>IllegalStateException</tt>. * <p> * <b>Restrictions on usage in Java EE</b> This method must not be used in a * Java EE EJB or web container. Doing so may cause a {@code JMSException} * to be thrown though this is not guaranteed. * <p> * <b>Message headers</b> 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 <tt>CompletionListener</tt> has been * invoked. If the <tt>CompletionListener</tt>'s <tt>onException</tt> method * is called then the state of these message header fields and properties is * undefined. * <p> * <b>Restrictions on threading</b>: 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. * <p> * Setting a <tt>CompletionListener</tt> does not cause the session to be * dedicated to the thread of control which calls the * <tt>CompletionListener</tt>. The application thread may therefore * continue to use the session after performing an asynchronous send. * However the <tt>CompletionListener</tt>'s callback methods must not use * the session if an application thread might be using the session at the * same time. * <p> * <b>Use of the <tt>CompletionListener</tt> by the JMS provider</b>: A * session will only invoke one <tt>CompletionListener</tt> callback method * at a time. For a given <tt>MessageProducer</tt>, callbacks (both * {@code onCompletion} and {@code onException}) will be performed * in the same order as the corresponding calls to the asynchronous send * method. * A JMS provider must not invoke the <tt>CompletionListener</tt> from the * thread that is calling the asynchronous <tt>send</tt> method. * <p> * <b>Restrictions on the use of the Message object</b>: Applications which * perform an asynchronous send must take account of the restriction that a * <tt>Message</tt> object is designed to be accessed by one logical thread * of control at a time and does not support concurrent use. * <p> * After the <tt>send</tt> method has returned, the application must not * attempt to read the headers, properties or body of the * <tt>Message</tt> object until the <tt>CompletionListener</tt>'s * <tt>onCompletion</tt> or <tt>onException</tt> method has been called. * This is because the JMS provider may be modifying the <tt>Message</tt> * object in another thread during this time. The JMS provider may throw an * <tt>JMSException</tt> if the application attempts to access or modify the * <tt>Message</tt> object after the <tt>send</tt> method has returned and * before the <tt>CompletionListener</tt> 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 {@code CompletionListener} to be notified when the send * has completed * * @exception JMSException * if an internal error occurs * @exception MessageFormatException * if an invalid message is specified. * @exception InvalidDestinationException * if a client uses this method with an invalid destination. * @exception java.lang.IllegalArgumentException * if the specified {@code CompletionListener} is null * @exception java.lang.UnsupportedOperationException * if a client uses this method with a * {@code MessageProducer} that specified a destination * at creation time. * * @see javax.jms.Session#createProducer * @see javax.jms.CompletionListener * * @since JMS 2.0 */ void send(Destination destination, Message message, int deliveryMode, int priority, long timeToLive, CompletionListener completionListener) throws JMSException; }