| <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd"> |
| <!-- NewPage --> |
| <html lang="en"> |
| <head> |
| <title>MessageProducer</title> |
| <link rel="stylesheet" type="text/css" href="../../stylesheet.css" title="Style"> |
| <script type="text/javascript" src="../../script.js"></script> |
| </head> |
| <body> |
| <script type="text/javascript"><!-- |
| try { |
| if (location.href.indexOf('is-external=true') == -1) { |
| parent.document.title="MessageProducer"; |
| } |
| } |
| catch(err) { |
| } |
| //--> |
| var methods = {"i0":6,"i1":6,"i2":6,"i3":6,"i4":6,"i5":6,"i6":6,"i7":6,"i8":6,"i9":6,"i10":6,"i11":6,"i12":6,"i13":6,"i14":6,"i15":6,"i16":6,"i17":6,"i18":6,"i19":6,"i20":6,"i21":6}; |
| var tabs = {65535:["t0","All Methods"],2:["t2","Instance Methods"],4:["t3","Abstract Methods"]}; |
| var altColor = "altColor"; |
| var rowColor = "rowColor"; |
| var tableTab = "tableTab"; |
| var activeTableTab = "activeTableTab"; |
| </script> |
| <noscript> |
| <div>JavaScript is disabled on your browser.</div> |
| </noscript> |
| <!-- ========= START OF TOP NAVBAR ======= --> |
| <div class="topNav"><a name="navbar.top"> |
| <!-- --> |
| </a> |
| <div class="skipNav"><a href="#skip.navbar.top" title="Skip navigation links">Skip navigation links</a></div> |
| <a name="navbar.top.firstrow"> |
| <!-- --> |
| </a> |
| <ul class="navList" title="Navigation"> |
| <li><a href="../../overview-summary.html">Overview</a></li> |
| <li><a href="package-summary.html">Package</a></li> |
| <li class="navBarCell1Rev">Class</li> |
| <li><a href="package-tree.html">Tree</a></li> |
| <li><a href="../../deprecated-list.html">Deprecated</a></li> |
| <li><a href="../../index-all.html">Index</a></li> |
| <li><a href="../../help-doc.html">Help</a></li> |
| </ul> |
| </div> |
| <div class="subNav"> |
| <ul class="navList"> |
| <li><a href="../../javax/jms/MessageNotWriteableRuntimeException.html" title="class in javax.jms"><span class="typeNameLink">Prev Class</span></a></li> |
| <li><a href="../../javax/jms/ObjectMessage.html" title="interface in javax.jms"><span class="typeNameLink">Next Class</span></a></li> |
| </ul> |
| <ul class="navList"> |
| <li><a href="../../index.html?javax/jms/MessageProducer.html" target="_top">Frames</a></li> |
| <li><a href="MessageProducer.html" target="_top">No Frames</a></li> |
| </ul> |
| <ul class="navList" id="allclasses_navbar_top"> |
| <li><a href="../../allclasses-noframe.html">All Classes</a></li> |
| </ul> |
| <div> |
| <script type="text/javascript"><!-- |
| allClassesLink = document.getElementById("allclasses_navbar_top"); |
| if(window==top) { |
| allClassesLink.style.display = "block"; |
| } |
| else { |
| allClassesLink.style.display = "none"; |
| } |
| //--> |
| </script> |
| </div> |
| <div> |
| <ul class="subNavList"> |
| <li>Summary: </li> |
| <li>Nested | </li> |
| <li>Field | </li> |
| <li>Constr | </li> |
| <li><a href="#method.summary">Method</a></li> |
| </ul> |
| <ul class="subNavList"> |
| <li>Detail: </li> |
| <li>Field | </li> |
| <li>Constr | </li> |
| <li><a href="#method.detail">Method</a></li> |
| </ul> |
| </div> |
| <a name="skip.navbar.top"> |
| <!-- --> |
| </a></div> |
| <!-- ========= END OF TOP NAVBAR ========= --> |
| <!-- ======== START OF CLASS DATA ======== --> |
| <div class="header"> |
| <div class="subTitle">javax.jms</div> |
| <h2 title="Interface MessageProducer" class="title">Interface MessageProducer</h2> |
| </div> |
| <div class="contentContainer"> |
| <div class="description"> |
| <ul class="blockList"> |
| <li class="blockList"> |
| <dl> |
| <dt>All Superinterfaces:</dt> |
| <dd>java.lang.AutoCloseable</dd> |
| </dl> |
| <dl> |
| <dt>All Known Subinterfaces:</dt> |
| <dd><a href="../../javax/jms/QueueSender.html" title="interface in javax.jms">QueueSender</a>, <a href="../../javax/jms/TopicPublisher.html" title="interface in javax.jms">TopicPublisher</a></dd> |
| </dl> |
| <hr> |
| <br> |
| <pre>public interface <span class="typeNameLabel">MessageProducer</span> |
| extends java.lang.AutoCloseable</pre> |
| <div class="block">A client uses a <code>MessageProducer</code> object to send messages to a destination. A <code>MessageProducer</code> object is |
| created by passing a <code>Destination</code> object to a message-producer creation method supplied by a session. |
| |
| <p> |
| <code>MessageProducer</code> 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</code> 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.</div> |
| <dl> |
| <dt><span class="simpleTagLabel">Since:</span></dt> |
| <dd>JMS 1.0</dd> |
| <dt><span class="seeLabel">See Also:</span></dt> |
| <dd><a href="../../javax/jms/TopicPublisher.html" title="interface in javax.jms"><code>TopicPublisher</code></a>, |
| <a href="../../javax/jms/QueueSender.html" title="interface in javax.jms"><code>QueueSender</code></a>, |
| <a href="../../javax/jms/Session.html#createProducer-javax.jms.Destination-"><code>Session.createProducer(javax.jms.Destination)</code></a></dd> |
| </dl> |
| </li> |
| </ul> |
| </div> |
| <div class="summary"> |
| <ul class="blockList"> |
| <li class="blockList"> |
| <!-- ========== METHOD SUMMARY =========== --> |
| <ul class="blockList"> |
| <li class="blockList"><a name="method.summary"> |
| <!-- --> |
| </a> |
| <h3>Method Summary</h3> |
| <table class="memberSummary" border="0" cellpadding="3" cellspacing="0" summary="Method Summary table, listing methods, and an explanation"> |
| <caption><span id="t0" class="activeTableTab"><span>All Methods</span><span class="tabEnd"> </span></span><span id="t2" class="tableTab"><span><a href="javascript:show(2);">Instance Methods</a></span><span class="tabEnd"> </span></span><span id="t3" class="tableTab"><span><a href="javascript:show(4);">Abstract Methods</a></span><span class="tabEnd"> </span></span></caption> |
| <tr> |
| <th class="colFirst" scope="col">Modifier and Type</th> |
| <th class="colLast" scope="col">Method and Description</th> |
| </tr> |
| <tr id="i0" class="altColor"> |
| <td class="colFirst"><code>void</code></td> |
| <td class="colLast"><code><span class="memberNameLink"><a href="../../javax/jms/MessageProducer.html#close--">close</a></span>()</code> |
| <div class="block">Closes the message producer.</div> |
| </td> |
| </tr> |
| <tr id="i1" class="rowColor"> |
| <td class="colFirst"><code>long</code></td> |
| <td class="colLast"><code><span class="memberNameLink"><a href="../../javax/jms/MessageProducer.html#getDeliveryDelay--">getDeliveryDelay</a></span>()</code> |
| <div class="block">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.</div> |
| </td> |
| </tr> |
| <tr id="i2" class="altColor"> |
| <td class="colFirst"><code>int</code></td> |
| <td class="colLast"><code><span class="memberNameLink"><a href="../../javax/jms/MessageProducer.html#getDeliveryMode--">getDeliveryMode</a></span>()</code> |
| <div class="block">Gets the producer's default delivery mode.</div> |
| </td> |
| </tr> |
| <tr id="i3" class="rowColor"> |
| <td class="colFirst"><code><a href="../../javax/jms/Destination.html" title="interface in javax.jms">Destination</a></code></td> |
| <td class="colLast"><code><span class="memberNameLink"><a href="../../javax/jms/MessageProducer.html#getDestination--">getDestination</a></span>()</code> |
| <div class="block">Gets the destination associated with this <code>MessageProducer</code>.</div> |
| </td> |
| </tr> |
| <tr id="i4" class="altColor"> |
| <td class="colFirst"><code>boolean</code></td> |
| <td class="colLast"><code><span class="memberNameLink"><a href="../../javax/jms/MessageProducer.html#getDisableMessageID--">getDisableMessageID</a></span>()</code> |
| <div class="block">Gets an indication of whether message IDs are disabled.</div> |
| </td> |
| </tr> |
| <tr id="i5" class="rowColor"> |
| <td class="colFirst"><code>boolean</code></td> |
| <td class="colLast"><code><span class="memberNameLink"><a href="../../javax/jms/MessageProducer.html#getDisableMessageTimestamp--">getDisableMessageTimestamp</a></span>()</code> |
| <div class="block">Gets an indication of whether message timestamps are disabled.</div> |
| </td> |
| </tr> |
| <tr id="i6" class="altColor"> |
| <td class="colFirst"><code>int</code></td> |
| <td class="colLast"><code><span class="memberNameLink"><a href="../../javax/jms/MessageProducer.html#getPriority--">getPriority</a></span>()</code> |
| <div class="block">Gets the producer's default priority.</div> |
| </td> |
| </tr> |
| <tr id="i7" class="rowColor"> |
| <td class="colFirst"><code>long</code></td> |
| <td class="colLast"><code><span class="memberNameLink"><a href="../../javax/jms/MessageProducer.html#getTimeToLive--">getTimeToLive</a></span>()</code> |
| <div class="block">Gets the default length of time in milliseconds from its dispatch time that a produced message should be retained by |
| the message system.</div> |
| </td> |
| </tr> |
| <tr id="i8" class="altColor"> |
| <td class="colFirst"><code>void</code></td> |
| <td class="colLast"><code><span class="memberNameLink"><a href="../../javax/jms/MessageProducer.html#send-javax.jms.Destination-javax.jms.Message-">send</a></span>(<a href="../../javax/jms/Destination.html" title="interface in javax.jms">Destination</a> destination, |
| <a href="../../javax/jms/Message.html" title="interface in javax.jms">Message</a> message)</code> |
| <div class="block">Sends a message to a destination for an unidentified message producer using the <code>MessageProducer</code>'s default |
| delivery mode, priority, and time to live.</div> |
| </td> |
| </tr> |
| <tr id="i9" class="rowColor"> |
| <td class="colFirst"><code>void</code></td> |
| <td class="colLast"><code><span class="memberNameLink"><a href="../../javax/jms/MessageProducer.html#send-javax.jms.Destination-javax.jms.Message-javax.jms.CompletionListener-">send</a></span>(<a href="../../javax/jms/Destination.html" title="interface in javax.jms">Destination</a> destination, |
| <a href="../../javax/jms/Message.html" title="interface in javax.jms">Message</a> message, |
| <a href="../../javax/jms/CompletionListener.html" title="interface in javax.jms">CompletionListener</a> completionListener)</code> |
| <div class="block">Sends a message to a destination for an unidentified message producer, using the <code>MessageProducer</code>'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.</div> |
| </td> |
| </tr> |
| <tr id="i10" class="altColor"> |
| <td class="colFirst"><code>void</code></td> |
| <td class="colLast"><code><span class="memberNameLink"><a href="../../javax/jms/MessageProducer.html#send-javax.jms.Destination-javax.jms.Message-int-int-long-">send</a></span>(<a href="../../javax/jms/Destination.html" title="interface in javax.jms">Destination</a> destination, |
| <a href="../../javax/jms/Message.html" title="interface in javax.jms">Message</a> message, |
| int deliveryMode, |
| int priority, |
| long timeToLive)</code> |
| <div class="block">Sends a message to a destination for an unidentified message producer, specifying delivery mode, priority and time to |
| live.</div> |
| </td> |
| </tr> |
| <tr id="i11" class="rowColor"> |
| <td class="colFirst"><code>void</code></td> |
| <td class="colLast"><code><span class="memberNameLink"><a href="../../javax/jms/MessageProducer.html#send-javax.jms.Destination-javax.jms.Message-int-int-long-javax.jms.CompletionListener-">send</a></span>(<a href="../../javax/jms/Destination.html" title="interface in javax.jms">Destination</a> destination, |
| <a href="../../javax/jms/Message.html" title="interface in javax.jms">Message</a> message, |
| int deliveryMode, |
| int priority, |
| long timeToLive, |
| <a href="../../javax/jms/CompletionListener.html" title="interface in javax.jms">CompletionListener</a> completionListener)</code> |
| <div class="block">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.</div> |
| </td> |
| </tr> |
| <tr id="i12" class="altColor"> |
| <td class="colFirst"><code>void</code></td> |
| <td class="colLast"><code><span class="memberNameLink"><a href="../../javax/jms/MessageProducer.html#send-javax.jms.Message-">send</a></span>(<a href="../../javax/jms/Message.html" title="interface in javax.jms">Message</a> message)</code> |
| <div class="block">Sends a message using the <code>MessageProducer</code>'s default delivery mode, priority, and time to live.</div> |
| </td> |
| </tr> |
| <tr id="i13" class="rowColor"> |
| <td class="colFirst"><code>void</code></td> |
| <td class="colLast"><code><span class="memberNameLink"><a href="../../javax/jms/MessageProducer.html#send-javax.jms.Message-javax.jms.CompletionListener-">send</a></span>(<a href="../../javax/jms/Message.html" title="interface in javax.jms">Message</a> message, |
| <a href="../../javax/jms/CompletionListener.html" title="interface in javax.jms">CompletionListener</a> completionListener)</code> |
| <div class="block">Sends a message using the <code>MessageProducer</code>'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.</div> |
| </td> |
| </tr> |
| <tr id="i14" class="altColor"> |
| <td class="colFirst"><code>void</code></td> |
| <td class="colLast"><code><span class="memberNameLink"><a href="../../javax/jms/MessageProducer.html#send-javax.jms.Message-int-int-long-">send</a></span>(<a href="../../javax/jms/Message.html" title="interface in javax.jms">Message</a> message, |
| int deliveryMode, |
| int priority, |
| long timeToLive)</code> |
| <div class="block">Sends a message, specifying delivery mode, priority, and time to live.</div> |
| </td> |
| </tr> |
| <tr id="i15" class="rowColor"> |
| <td class="colFirst"><code>void</code></td> |
| <td class="colLast"><code><span class="memberNameLink"><a href="../../javax/jms/MessageProducer.html#send-javax.jms.Message-int-int-long-javax.jms.CompletionListener-">send</a></span>(<a href="../../javax/jms/Message.html" title="interface in javax.jms">Message</a> message, |
| int deliveryMode, |
| int priority, |
| long timeToLive, |
| <a href="../../javax/jms/CompletionListener.html" title="interface in javax.jms">CompletionListener</a> completionListener)</code> |
| <div class="block">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.</div> |
| </td> |
| </tr> |
| <tr id="i16" class="altColor"> |
| <td class="colFirst"><code>void</code></td> |
| <td class="colLast"><code><span class="memberNameLink"><a href="../../javax/jms/MessageProducer.html#setDeliveryDelay-long-">setDeliveryDelay</a></span>(long deliveryDelay)</code> |
| <div class="block">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.</div> |
| </td> |
| </tr> |
| <tr id="i17" class="rowColor"> |
| <td class="colFirst"><code>void</code></td> |
| <td class="colLast"><code><span class="memberNameLink"><a href="../../javax/jms/MessageProducer.html#setDeliveryMode-int-">setDeliveryMode</a></span>(int deliveryMode)</code> |
| <div class="block">Sets the producer's default delivery mode.</div> |
| </td> |
| </tr> |
| <tr id="i18" class="altColor"> |
| <td class="colFirst"><code>void</code></td> |
| <td class="colLast"><code><span class="memberNameLink"><a href="../../javax/jms/MessageProducer.html#setDisableMessageID-boolean-">setDisableMessageID</a></span>(boolean value)</code> |
| <div class="block">Specify whether message IDs may be disabled.</div> |
| </td> |
| </tr> |
| <tr id="i19" class="rowColor"> |
| <td class="colFirst"><code>void</code></td> |
| <td class="colLast"><code><span class="memberNameLink"><a href="../../javax/jms/MessageProducer.html#setDisableMessageTimestamp-boolean-">setDisableMessageTimestamp</a></span>(boolean value)</code> |
| <div class="block">Specify whether message timestamps may be disabled.</div> |
| </td> |
| </tr> |
| <tr id="i20" class="altColor"> |
| <td class="colFirst"><code>void</code></td> |
| <td class="colLast"><code><span class="memberNameLink"><a href="../../javax/jms/MessageProducer.html#setPriority-int-">setPriority</a></span>(int defaultPriority)</code> |
| <div class="block">Sets the producer's default priority.</div> |
| </td> |
| </tr> |
| <tr id="i21" class="rowColor"> |
| <td class="colFirst"><code>void</code></td> |
| <td class="colLast"><code><span class="memberNameLink"><a href="../../javax/jms/MessageProducer.html#setTimeToLive-long-">setTimeToLive</a></span>(long timeToLive)</code> |
| <div class="block">Sets the default length of time in milliseconds from its dispatch time that a produced message should be retained by |
| the message system.</div> |
| </td> |
| </tr> |
| </table> |
| </li> |
| </ul> |
| </li> |
| </ul> |
| </div> |
| <div class="details"> |
| <ul class="blockList"> |
| <li class="blockList"> |
| <!-- ============ METHOD DETAIL ========== --> |
| <ul class="blockList"> |
| <li class="blockList"><a name="method.detail"> |
| <!-- --> |
| </a> |
| <h3>Method Detail</h3> |
| <a name="setDisableMessageID-boolean-"> |
| <!-- --> |
| </a> |
| <ul class="blockList"> |
| <li class="blockList"> |
| <h4>setDisableMessageID</h4> |
| <pre>void setDisableMessageID(boolean value) |
| throws <a href="../../javax/jms/JMSException.html" title="class in javax.jms">JMSException</a></pre> |
| <div class="block">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</code>. 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.</div> |
| <dl> |
| <dt><span class="paramLabel">Parameters:</span></dt> |
| <dd><code>value</code> - indicates if message IDs may be disabled</dd> |
| <dt><span class="throwsLabel">Throws:</span></dt> |
| <dd><code><a href="../../javax/jms/JMSException.html" title="class in javax.jms">JMSException</a></code> - if the JMS provider fails to set message ID to disabled due to some internal error.</dd> |
| </dl> |
| </li> |
| </ul> |
| <a name="getDisableMessageID--"> |
| <!-- --> |
| </a> |
| <ul class="blockList"> |
| <li class="blockList"> |
| <h4>getDisableMessageID</h4> |
| <pre>boolean getDisableMessageID() |
| throws <a href="../../javax/jms/JMSException.html" title="class in javax.jms">JMSException</a></pre> |
| <div class="block">Gets an indication of whether message IDs are disabled.</div> |
| <dl> |
| <dt><span class="returnLabel">Returns:</span></dt> |
| <dd>an indication of whether message IDs are disabled</dd> |
| <dt><span class="throwsLabel">Throws:</span></dt> |
| <dd><code><a href="../../javax/jms/JMSException.html" title="class in javax.jms">JMSException</a></code> - if the JMS provider fails to determine if message IDs are disabled due to some internal |
| error.</dd> |
| </dl> |
| </li> |
| </ul> |
| <a name="setDisableMessageTimestamp-boolean-"> |
| <!-- --> |
| </a> |
| <ul class="blockList"> |
| <li class="blockList"> |
| <h4>setDisableMessageTimestamp</h4> |
| <pre>void setDisableMessageTimestamp(boolean value) |
| throws <a href="../../javax/jms/JMSException.html" title="class in javax.jms">JMSException</a></pre> |
| <div class="block">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</code>. 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.</div> |
| <dl> |
| <dt><span class="paramLabel">Parameters:</span></dt> |
| <dd><code>value</code> - indicates whether message timestamps may be disabled</dd> |
| <dt><span class="throwsLabel">Throws:</span></dt> |
| <dd><code><a href="../../javax/jms/JMSException.html" title="class in javax.jms">JMSException</a></code> - if the JMS provider fails to set timestamps to disabled due to some internal error.</dd> |
| </dl> |
| </li> |
| </ul> |
| <a name="getDisableMessageTimestamp--"> |
| <!-- --> |
| </a> |
| <ul class="blockList"> |
| <li class="blockList"> |
| <h4>getDisableMessageTimestamp</h4> |
| <pre>boolean getDisableMessageTimestamp() |
| throws <a href="../../javax/jms/JMSException.html" title="class in javax.jms">JMSException</a></pre> |
| <div class="block">Gets an indication of whether message timestamps are disabled.</div> |
| <dl> |
| <dt><span class="returnLabel">Returns:</span></dt> |
| <dd>an indication of whether message timestamps are disabled</dd> |
| <dt><span class="throwsLabel">Throws:</span></dt> |
| <dd><code><a href="../../javax/jms/JMSException.html" title="class in javax.jms">JMSException</a></code> - if the JMS provider fails to determine if timestamps are disabled due to some internal error.</dd> |
| </dl> |
| </li> |
| </ul> |
| <a name="setDeliveryMode-int-"> |
| <!-- --> |
| </a> |
| <ul class="blockList"> |
| <li class="blockList"> |
| <h4>setDeliveryMode</h4> |
| <pre>void setDeliveryMode(int deliveryMode) |
| throws <a href="../../javax/jms/JMSException.html" title="class in javax.jms">JMSException</a></pre> |
| <div class="block">Sets the producer's default delivery mode. |
| |
| <p> |
| Delivery mode is set to <code>PERSISTENT</code> by default.</div> |
| <dl> |
| <dt><span class="paramLabel">Parameters:</span></dt> |
| <dd><code>deliveryMode</code> - the message delivery mode for this message producer; legal values are |
| <code>DeliveryMode.NON_PERSISTENT</code> and <code>DeliveryMode.PERSISTENT</code></dd> |
| <dt><span class="throwsLabel">Throws:</span></dt> |
| <dd><code><a href="../../javax/jms/JMSException.html" title="class in javax.jms">JMSException</a></code> - if the JMS provider fails to set the delivery mode due to some internal error.</dd> |
| <dt><span class="seeLabel">See Also:</span></dt> |
| <dd><a href="../../javax/jms/MessageProducer.html#getDeliveryMode--"><code>getDeliveryMode()</code></a>, |
| <a href="../../javax/jms/DeliveryMode.html#NON_PERSISTENT"><code>DeliveryMode.NON_PERSISTENT</code></a>, |
| <a href="../../javax/jms/DeliveryMode.html#PERSISTENT"><code>DeliveryMode.PERSISTENT</code></a>, |
| <a href="../../javax/jms/Message.html#DEFAULT_DELIVERY_MODE"><code>Message.DEFAULT_DELIVERY_MODE</code></a></dd> |
| </dl> |
| </li> |
| </ul> |
| <a name="getDeliveryMode--"> |
| <!-- --> |
| </a> |
| <ul class="blockList"> |
| <li class="blockList"> |
| <h4>getDeliveryMode</h4> |
| <pre>int getDeliveryMode() |
| throws <a href="../../javax/jms/JMSException.html" title="class in javax.jms">JMSException</a></pre> |
| <div class="block">Gets the producer's default delivery mode.</div> |
| <dl> |
| <dt><span class="returnLabel">Returns:</span></dt> |
| <dd>the message delivery mode for this message producer</dd> |
| <dt><span class="throwsLabel">Throws:</span></dt> |
| <dd><code><a href="../../javax/jms/JMSException.html" title="class in javax.jms">JMSException</a></code> - if the JMS provider fails to get the delivery mode due to some internal error.</dd> |
| <dt><span class="seeLabel">See Also:</span></dt> |
| <dd><a href="../../javax/jms/MessageProducer.html#setDeliveryMode-int-"><code>setDeliveryMode(int)</code></a></dd> |
| </dl> |
| </li> |
| </ul> |
| <a name="setPriority-int-"> |
| <!-- --> |
| </a> |
| <ul class="blockList"> |
| <li class="blockList"> |
| <h4>setPriority</h4> |
| <pre>void setPriority(int defaultPriority) |
| throws <a href="../../javax/jms/JMSException.html" title="class in javax.jms">JMSException</a></pre> |
| <div class="block">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.</div> |
| <dl> |
| <dt><span class="paramLabel">Parameters:</span></dt> |
| <dd><code>defaultPriority</code> - the message priority for this message producer; must be a value between 0 and 9</dd> |
| <dt><span class="throwsLabel">Throws:</span></dt> |
| <dd><code><a href="../../javax/jms/JMSException.html" title="class in javax.jms">JMSException</a></code> - if the JMS provider fails to set the priority due to some internal error.</dd> |
| <dt><span class="seeLabel">See Also:</span></dt> |
| <dd><a href="../../javax/jms/MessageProducer.html#getPriority--"><code>getPriority()</code></a>, |
| <a href="../../javax/jms/Message.html#DEFAULT_PRIORITY"><code>Message.DEFAULT_PRIORITY</code></a></dd> |
| </dl> |
| </li> |
| </ul> |
| <a name="getPriority--"> |
| <!-- --> |
| </a> |
| <ul class="blockList"> |
| <li class="blockList"> |
| <h4>getPriority</h4> |
| <pre>int getPriority() |
| throws <a href="../../javax/jms/JMSException.html" title="class in javax.jms">JMSException</a></pre> |
| <div class="block">Gets the producer's default priority.</div> |
| <dl> |
| <dt><span class="returnLabel">Returns:</span></dt> |
| <dd>the message priority for this message producer</dd> |
| <dt><span class="throwsLabel">Throws:</span></dt> |
| <dd><code><a href="../../javax/jms/JMSException.html" title="class in javax.jms">JMSException</a></code> - if the JMS provider fails to get the priority due to some internal error.</dd> |
| <dt><span class="seeLabel">See Also:</span></dt> |
| <dd><a href="../../javax/jms/MessageProducer.html#setPriority-int-"><code>setPriority(int)</code></a></dd> |
| </dl> |
| </li> |
| </ul> |
| <a name="setTimeToLive-long-"> |
| <!-- --> |
| </a> |
| <ul class="blockList"> |
| <li class="blockList"> |
| <h4>setTimeToLive</h4> |
| <pre>void setTimeToLive(long timeToLive) |
| throws <a href="../../javax/jms/JMSException.html" title="class in javax.jms">JMSException</a></pre> |
| <div class="block">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.</div> |
| <dl> |
| <dt><span class="paramLabel">Parameters:</span></dt> |
| <dd><code>timeToLive</code> - the message time to live in milliseconds; zero is unlimited</dd> |
| <dt><span class="throwsLabel">Throws:</span></dt> |
| <dd><code><a href="../../javax/jms/JMSException.html" title="class in javax.jms">JMSException</a></code> - if the JMS provider fails to set the time to live due to some internal error.</dd> |
| <dt><span class="seeLabel">See Also:</span></dt> |
| <dd><a href="../../javax/jms/MessageProducer.html#getTimeToLive--"><code>getTimeToLive()</code></a>, |
| <a href="../../javax/jms/Message.html#DEFAULT_TIME_TO_LIVE"><code>Message.DEFAULT_TIME_TO_LIVE</code></a></dd> |
| </dl> |
| </li> |
| </ul> |
| <a name="getTimeToLive--"> |
| <!-- --> |
| </a> |
| <ul class="blockList"> |
| <li class="blockList"> |
| <h4>getTimeToLive</h4> |
| <pre>long getTimeToLive() |
| throws <a href="../../javax/jms/JMSException.html" title="class in javax.jms">JMSException</a></pre> |
| <div class="block">Gets the default length of time in milliseconds from its dispatch time that a produced message should be retained by |
| the message system.</div> |
| <dl> |
| <dt><span class="returnLabel">Returns:</span></dt> |
| <dd>the message time to live in milliseconds; zero is unlimited</dd> |
| <dt><span class="throwsLabel">Throws:</span></dt> |
| <dd><code><a href="../../javax/jms/JMSException.html" title="class in javax.jms">JMSException</a></code> - if the JMS provider fails to get the time to live due to some internal error.</dd> |
| <dt><span class="seeLabel">See Also:</span></dt> |
| <dd><a href="../../javax/jms/MessageProducer.html#setTimeToLive-long-"><code>setTimeToLive(long)</code></a></dd> |
| </dl> |
| </li> |
| </ul> |
| <a name="setDeliveryDelay-long-"> |
| <!-- --> |
| </a> |
| <ul class="blockList"> |
| <li class="blockList"> |
| <h4>setDeliveryDelay</h4> |
| <pre>void setDeliveryDelay(long deliveryDelay) |
| throws <a href="../../javax/jms/JMSException.html" title="class in javax.jms">JMSException</a></pre> |
| <div class="block">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.</div> |
| <dl> |
| <dt><span class="paramLabel">Parameters:</span></dt> |
| <dd><code>deliveryDelay</code> - the delivery delay in milliseconds.</dd> |
| <dt><span class="throwsLabel">Throws:</span></dt> |
| <dd><code><a href="../../javax/jms/JMSException.html" title="class in javax.jms">JMSException</a></code> - if the JMS provider fails to set the delivery delay due to some internal error.</dd> |
| <dt><span class="simpleTagLabel">Since:</span></dt> |
| <dd>JMS 2.0</dd> |
| <dt><span class="seeLabel">See Also:</span></dt> |
| <dd><a href="../../javax/jms/MessageProducer.html#getDeliveryDelay--"><code>getDeliveryDelay()</code></a>, |
| <a href="../../javax/jms/Message.html#DEFAULT_DELIVERY_DELAY"><code>Message.DEFAULT_DELIVERY_DELAY</code></a></dd> |
| </dl> |
| </li> |
| </ul> |
| <a name="getDeliveryDelay--"> |
| <!-- --> |
| </a> |
| <ul class="blockList"> |
| <li class="blockList"> |
| <h4>getDeliveryDelay</h4> |
| <pre>long getDeliveryDelay() |
| throws <a href="../../javax/jms/JMSException.html" title="class in javax.jms">JMSException</a></pre> |
| <div class="block">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.</div> |
| <dl> |
| <dt><span class="returnLabel">Returns:</span></dt> |
| <dd>the delivery delay in milliseconds.</dd> |
| <dt><span class="throwsLabel">Throws:</span></dt> |
| <dd><code><a href="../../javax/jms/JMSException.html" title="class in javax.jms">JMSException</a></code> - if the JMS provider fails to get the delivery delay due to some internal error.</dd> |
| <dt><span class="simpleTagLabel">Since:</span></dt> |
| <dd>JMS 2.0</dd> |
| <dt><span class="seeLabel">See Also:</span></dt> |
| <dd><a href="../../javax/jms/MessageProducer.html#setDeliveryDelay-long-"><code>setDeliveryDelay(long)</code></a></dd> |
| </dl> |
| </li> |
| </ul> |
| <a name="getDestination--"> |
| <!-- --> |
| </a> |
| <ul class="blockList"> |
| <li class="blockList"> |
| <h4>getDestination</h4> |
| <pre><a href="../../javax/jms/Destination.html" title="interface in javax.jms">Destination</a> getDestination() |
| throws <a href="../../javax/jms/JMSException.html" title="class in javax.jms">JMSException</a></pre> |
| <div class="block">Gets the destination associated with this <code>MessageProducer</code>.</div> |
| <dl> |
| <dt><span class="returnLabel">Returns:</span></dt> |
| <dd>this producer's <code>Destination</code></dd> |
| <dt><span class="throwsLabel">Throws:</span></dt> |
| <dd><code><a href="../../javax/jms/JMSException.html" title="class in javax.jms">JMSException</a></code> - if the JMS provider fails to get the destination for this <code>MessageProducer</code> due to some |
| internal error.</dd> |
| <dt><span class="simpleTagLabel">Since:</span></dt> |
| <dd>JMS 1.1</dd> |
| </dl> |
| </li> |
| </ul> |
| <a name="close--"> |
| <!-- --> |
| </a> |
| <ul class="blockList"> |
| <li class="blockList"> |
| <h4>close</h4> |
| <pre>void close() |
| throws <a href="../../javax/jms/JMSException.html" title="class in javax.jms">JMSException</a></pre> |
| <div class="block">Closes the message producer. |
| |
| <p> |
| Since a provider may allocate some resources on behalf of a <code>MessageProducer</code> 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.</div> |
| <dl> |
| <dt><span class="overrideSpecifyLabel">Specified by:</span></dt> |
| <dd><code>close</code> in interface <code>java.lang.AutoCloseable</code></dd> |
| <dt><span class="throwsLabel">Throws:</span></dt> |
| <dd><code><a href="../../javax/jms/IllegalStateException.html" title="class in javax.jms">IllegalStateException</a></code> - this method has been called by a <tt>CompletionListener</tt> callback method on its |
| own <tt>MessageProducer</tt></dd> |
| <dd><code><a href="../../javax/jms/JMSException.html" title="class in javax.jms">JMSException</a></code> - if the JMS provider fails to close the producer due to some internal error.</dd> |
| </dl> |
| </li> |
| </ul> |
| <a name="send-javax.jms.Message-"> |
| <!-- --> |
| </a> |
| <ul class="blockList"> |
| <li class="blockList"> |
| <h4>send</h4> |
| <pre>void send(<a href="../../javax/jms/Message.html" title="interface in javax.jms">Message</a> message) |
| throws <a href="../../javax/jms/JMSException.html" title="class in javax.jms">JMSException</a></pre> |
| <div class="block">Sends a message using the <code>MessageProducer</code>'s default delivery mode, priority, and time to live.</div> |
| <dl> |
| <dt><span class="paramLabel">Parameters:</span></dt> |
| <dd><code>message</code> - the message to send</dd> |
| <dt><span class="throwsLabel">Throws:</span></dt> |
| <dd><code><a href="../../javax/jms/JMSException.html" title="class in javax.jms">JMSException</a></code> - if the JMS provider fails to send the message due to some internal error.</dd> |
| <dd><code><a href="../../javax/jms/MessageFormatException.html" title="class in javax.jms">MessageFormatException</a></code> - if an invalid message is specified.</dd> |
| <dd><code><a href="../../javax/jms/InvalidDestinationException.html" title="class in javax.jms">InvalidDestinationException</a></code> - if a client uses this method with a <code>MessageProducer</code> with an invalid |
| destination.</dd> |
| <dd><code>java.lang.UnsupportedOperationException</code> - if a client uses this method with a <code>MessageProducer</code> that |
| did not specify a destination at creation time.</dd> |
| <dt><span class="simpleTagLabel">Since:</span></dt> |
| <dd>JMS 1.1</dd> |
| <dt><span class="seeLabel">See Also:</span></dt> |
| <dd><a href="../../javax/jms/Session.html#createProducer-javax.jms.Destination-"><code>Session.createProducer(javax.jms.Destination)</code></a></dd> |
| </dl> |
| </li> |
| </ul> |
| <a name="send-javax.jms.Message-int-int-long-"> |
| <!-- --> |
| </a> |
| <ul class="blockList"> |
| <li class="blockList"> |
| <h4>send</h4> |
| <pre>void send(<a href="../../javax/jms/Message.html" title="interface in javax.jms">Message</a> message, |
| int deliveryMode, |
| int priority, |
| long timeToLive) |
| throws <a href="../../javax/jms/JMSException.html" title="class in javax.jms">JMSException</a></pre> |
| <div class="block">Sends a message, specifying delivery mode, priority, and time to live.</div> |
| <dl> |
| <dt><span class="paramLabel">Parameters:</span></dt> |
| <dd><code>message</code> - the message to send</dd> |
| <dd><code>deliveryMode</code> - the delivery mode to use</dd> |
| <dd><code>priority</code> - the priority for this message</dd> |
| <dd><code>timeToLive</code> - the message's lifetime (in milliseconds)</dd> |
| <dt><span class="throwsLabel">Throws:</span></dt> |
| <dd><code><a href="../../javax/jms/JMSException.html" title="class in javax.jms">JMSException</a></code> - if the JMS provider fails to send the message due to some internal error.</dd> |
| <dd><code><a href="../../javax/jms/MessageFormatException.html" title="class in javax.jms">MessageFormatException</a></code> - if an invalid message is specified.</dd> |
| <dd><code><a href="../../javax/jms/InvalidDestinationException.html" title="class in javax.jms">InvalidDestinationException</a></code> - if a client uses this method with a <code>MessageProducer</code> with an invalid |
| destination.</dd> |
| <dd><code>java.lang.UnsupportedOperationException</code> - if a client uses this method with a <code>MessageProducer</code> that |
| did not specify a destination at creation time.</dd> |
| <dt><span class="simpleTagLabel">Since:</span></dt> |
| <dd>JMS 1.1</dd> |
| <dt><span class="seeLabel">See Also:</span></dt> |
| <dd><a href="../../javax/jms/Session.html#createProducer-javax.jms.Destination-"><code>Session.createProducer(javax.jms.Destination)</code></a></dd> |
| </dl> |
| </li> |
| </ul> |
| <a name="send-javax.jms.Destination-javax.jms.Message-"> |
| <!-- --> |
| </a> |
| <ul class="blockList"> |
| <li class="blockList"> |
| <h4>send</h4> |
| <pre>void send(<a href="../../javax/jms/Destination.html" title="interface in javax.jms">Destination</a> destination, |
| <a href="../../javax/jms/Message.html" title="interface in javax.jms">Message</a> message) |
| throws <a href="../../javax/jms/JMSException.html" title="class in javax.jms">JMSException</a></pre> |
| <div class="block">Sends a message to a destination for an unidentified message producer using the <code>MessageProducer</code>'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.</div> |
| <dl> |
| <dt><span class="paramLabel">Parameters:</span></dt> |
| <dd><code>destination</code> - the destination to send this message to</dd> |
| <dd><code>message</code> - the message to send</dd> |
| <dt><span class="throwsLabel">Throws:</span></dt> |
| <dd><code><a href="../../javax/jms/JMSException.html" title="class in javax.jms">JMSException</a></code> - if the JMS provider fails to send the message due to some internal error.</dd> |
| <dd><code><a href="../../javax/jms/MessageFormatException.html" title="class in javax.jms">MessageFormatException</a></code> - if an invalid message is specified.</dd> |
| <dd><code><a href="../../javax/jms/InvalidDestinationException.html" title="class in javax.jms">InvalidDestinationException</a></code> - if a client uses this method with an invalid destination.</dd> |
| <dd><code>java.lang.UnsupportedOperationException</code> - if a client uses this method with a <code>MessageProducer</code> that |
| specified a destination at creation time.</dd> |
| <dt><span class="simpleTagLabel">Since:</span></dt> |
| <dd>JMS 1.1</dd> |
| <dt><span class="seeLabel">See Also:</span></dt> |
| <dd><a href="../../javax/jms/Session.html#createProducer-javax.jms.Destination-"><code>Session.createProducer(javax.jms.Destination)</code></a></dd> |
| </dl> |
| </li> |
| </ul> |
| <a name="send-javax.jms.Destination-javax.jms.Message-int-int-long-"> |
| <!-- --> |
| </a> |
| <ul class="blockList"> |
| <li class="blockList"> |
| <h4>send</h4> |
| <pre>void send(<a href="../../javax/jms/Destination.html" title="interface in javax.jms">Destination</a> destination, |
| <a href="../../javax/jms/Message.html" title="interface in javax.jms">Message</a> message, |
| int deliveryMode, |
| int priority, |
| long timeToLive) |
| throws <a href="../../javax/jms/JMSException.html" title="class in javax.jms">JMSException</a></pre> |
| <div class="block">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.</div> |
| <dl> |
| <dt><span class="paramLabel">Parameters:</span></dt> |
| <dd><code>destination</code> - the destination to send this message to</dd> |
| <dd><code>message</code> - the message to send</dd> |
| <dd><code>deliveryMode</code> - the delivery mode to use</dd> |
| <dd><code>priority</code> - the priority for this message</dd> |
| <dd><code>timeToLive</code> - the message's lifetime (in milliseconds)</dd> |
| <dt><span class="throwsLabel">Throws:</span></dt> |
| <dd><code><a href="../../javax/jms/JMSException.html" title="class in javax.jms">JMSException</a></code> - if the JMS provider fails to send the message due to some internal error.</dd> |
| <dd><code><a href="../../javax/jms/MessageFormatException.html" title="class in javax.jms">MessageFormatException</a></code> - if an invalid message is specified.</dd> |
| <dd><code><a href="../../javax/jms/InvalidDestinationException.html" title="class in javax.jms">InvalidDestinationException</a></code> - if a client uses this method with an invalid destination.</dd> |
| <dd><code>java.lang.UnsupportedOperationException</code> - if a client uses this method with a <code>MessageProducer</code> that |
| specified a destination at creation time.</dd> |
| <dt><span class="simpleTagLabel">Since:</span></dt> |
| <dd>JMS 1.1</dd> |
| <dt><span class="seeLabel">See Also:</span></dt> |
| <dd><a href="../../javax/jms/Session.html#createProducer-javax.jms.Destination-"><code>Session.createProducer(javax.jms.Destination)</code></a></dd> |
| </dl> |
| </li> |
| </ul> |
| <a name="send-javax.jms.Message-javax.jms.CompletionListener-"> |
| <!-- --> |
| </a> |
| <ul class="blockList"> |
| <li class="blockList"> |
| <h4>send</h4> |
| <pre>void send(<a href="../../javax/jms/Message.html" title="interface in javax.jms">Message</a> message, |
| <a href="../../javax/jms/CompletionListener.html" title="interface in javax.jms">CompletionListener</a> completionListener) |
| throws <a href="../../javax/jms/JMSException.html" title="class in javax.jms">JMSException</a></pre> |
| <div class="block">Sends a message using the <code>MessageProducer</code>'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</code> 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</code> 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</code> 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</code> and <code>onException</code>) 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.</div> |
| <dl> |
| <dt><span class="paramLabel">Parameters:</span></dt> |
| <dd><code>message</code> - the message to send</dd> |
| <dd><code>completionListener</code> - a <code>CompletionListener</code> to be notified when the send has completed</dd> |
| <dt><span class="throwsLabel">Throws:</span></dt> |
| <dd><code><a href="../../javax/jms/JMSException.html" title="class in javax.jms">JMSException</a></code> - if an internal error occurs</dd> |
| <dd><code><a href="../../javax/jms/MessageFormatException.html" title="class in javax.jms">MessageFormatException</a></code> - if an invalid message is specified.</dd> |
| <dd><code><a href="../../javax/jms/InvalidDestinationException.html" title="class in javax.jms">InvalidDestinationException</a></code> - if a client uses this method with a <code>MessageProducer</code> with an invalid |
| destination.</dd> |
| <dd><code>java.lang.IllegalArgumentException</code> - if the specified <code>CompletionListener</code> is null</dd> |
| <dd><code>java.lang.UnsupportedOperationException</code> - if a client uses this method with a <code>MessageProducer</code> that |
| did not specify a destination at creation time.</dd> |
| <dt><span class="simpleTagLabel">Since:</span></dt> |
| <dd>JMS 2.0</dd> |
| <dt><span class="seeLabel">See Also:</span></dt> |
| <dd><a href="../../javax/jms/Session.html#createProducer-javax.jms.Destination-"><code>Session.createProducer(javax.jms.Destination)</code></a>, |
| <a href="../../javax/jms/CompletionListener.html" title="interface in javax.jms"><code>CompletionListener</code></a></dd> |
| </dl> |
| </li> |
| </ul> |
| <a name="send-javax.jms.Message-int-int-long-javax.jms.CompletionListener-"> |
| <!-- --> |
| </a> |
| <ul class="blockList"> |
| <li class="blockList"> |
| <h4>send</h4> |
| <pre>void send(<a href="../../javax/jms/Message.html" title="interface in javax.jms">Message</a> message, |
| int deliveryMode, |
| int priority, |
| long timeToLive, |
| <a href="../../javax/jms/CompletionListener.html" title="interface in javax.jms">CompletionListener</a> completionListener) |
| throws <a href="../../javax/jms/JMSException.html" title="class in javax.jms">JMSException</a></pre> |
| <div class="block">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</code> 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</code> 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</code> 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</code> and <code>onException</code>) 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.</div> |
| <dl> |
| <dt><span class="paramLabel">Parameters:</span></dt> |
| <dd><code>message</code> - the message to send</dd> |
| <dd><code>deliveryMode</code> - the delivery mode to use</dd> |
| <dd><code>priority</code> - the priority for this message</dd> |
| <dd><code>timeToLive</code> - the message's lifetime (in milliseconds)</dd> |
| <dd><code>completionListener</code> - a <code>CompletionListener</code> to be notified when the send has completed</dd> |
| <dt><span class="throwsLabel">Throws:</span></dt> |
| <dd><code><a href="../../javax/jms/JMSException.html" title="class in javax.jms">JMSException</a></code> - if an internal error occurs</dd> |
| <dd><code><a href="../../javax/jms/MessageFormatException.html" title="class in javax.jms">MessageFormatException</a></code> - if an invalid message is specified.</dd> |
| <dd><code><a href="../../javax/jms/InvalidDestinationException.html" title="class in javax.jms">InvalidDestinationException</a></code> - if a client uses this method with a <code>MessageProducer</code> with an invalid |
| destination.</dd> |
| <dd><code>java.lang.IllegalArgumentException</code> - if the specified <code>CompletionListener</code> is null</dd> |
| <dd><code>java.lang.UnsupportedOperationException</code> - if a client uses this method with a <code>MessageProducer</code> that |
| did not specify a destination at creation time.</dd> |
| <dt><span class="simpleTagLabel">Since:</span></dt> |
| <dd>JMS 2.0</dd> |
| <dt><span class="seeLabel">See Also:</span></dt> |
| <dd><a href="../../javax/jms/Session.html#createProducer-javax.jms.Destination-"><code>Session.createProducer(javax.jms.Destination)</code></a>, |
| <a href="../../javax/jms/CompletionListener.html" title="interface in javax.jms"><code>CompletionListener</code></a></dd> |
| </dl> |
| </li> |
| </ul> |
| <a name="send-javax.jms.Destination-javax.jms.Message-javax.jms.CompletionListener-"> |
| <!-- --> |
| </a> |
| <ul class="blockList"> |
| <li class="blockList"> |
| <h4>send</h4> |
| <pre>void send(<a href="../../javax/jms/Destination.html" title="interface in javax.jms">Destination</a> destination, |
| <a href="../../javax/jms/Message.html" title="interface in javax.jms">Message</a> message, |
| <a href="../../javax/jms/CompletionListener.html" title="interface in javax.jms">CompletionListener</a> completionListener) |
| throws <a href="../../javax/jms/JMSException.html" title="class in javax.jms">JMSException</a></pre> |
| <div class="block">Sends a message to a destination for an unidentified message producer, using the <code>MessageProducer</code>'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</code> 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</code> 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</code> 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</code> and <code>onException</code>) 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.</div> |
| <dl> |
| <dt><span class="paramLabel">Parameters:</span></dt> |
| <dd><code>destination</code> - the destination to send this message to</dd> |
| <dd><code>message</code> - the message to send</dd> |
| <dd><code>completionListener</code> - a <code>CompletionListener</code> to be notified when the send has completed</dd> |
| <dt><span class="throwsLabel">Throws:</span></dt> |
| <dd><code><a href="../../javax/jms/JMSException.html" title="class in javax.jms">JMSException</a></code> - if an internal error occurs</dd> |
| <dd><code><a href="../../javax/jms/MessageFormatException.html" title="class in javax.jms">MessageFormatException</a></code> - if an invalid message is specified.</dd> |
| <dd><code><a href="../../javax/jms/InvalidDestinationException.html" title="class in javax.jms">InvalidDestinationException</a></code> - if a client uses this method with an invalid destination</dd> |
| <dd><code>java.lang.IllegalArgumentException</code> - if the specified <code>CompletionListener</code> is null</dd> |
| <dd><code>java.lang.UnsupportedOperationException</code> - if a client uses this method with a <code>MessageProducer</code> that |
| specified a destination at creation time.</dd> |
| <dt><span class="simpleTagLabel">Since:</span></dt> |
| <dd>JMS 2.0</dd> |
| <dt><span class="seeLabel">See Also:</span></dt> |
| <dd><a href="../../javax/jms/Session.html#createProducer-javax.jms.Destination-"><code>Session.createProducer(javax.jms.Destination)</code></a>, |
| <a href="../../javax/jms/CompletionListener.html" title="interface in javax.jms"><code>CompletionListener</code></a></dd> |
| </dl> |
| </li> |
| </ul> |
| <a name="send-javax.jms.Destination-javax.jms.Message-int-int-long-javax.jms.CompletionListener-"> |
| <!-- --> |
| </a> |
| <ul class="blockListLast"> |
| <li class="blockList"> |
| <h4>send</h4> |
| <pre>void send(<a href="../../javax/jms/Destination.html" title="interface in javax.jms">Destination</a> destination, |
| <a href="../../javax/jms/Message.html" title="interface in javax.jms">Message</a> message, |
| int deliveryMode, |
| int priority, |
| long timeToLive, |
| <a href="../../javax/jms/CompletionListener.html" title="interface in javax.jms">CompletionListener</a> completionListener) |
| throws <a href="../../javax/jms/JMSException.html" title="class in javax.jms">JMSException</a></pre> |
| <div class="block">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</code> 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</code> 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</code> 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</code> and <code>onException</code>) 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.</div> |
| <dl> |
| <dt><span class="paramLabel">Parameters:</span></dt> |
| <dd><code>destination</code> - the destination to send this message to</dd> |
| <dd><code>message</code> - the message to send</dd> |
| <dd><code>deliveryMode</code> - the delivery mode to use</dd> |
| <dd><code>priority</code> - the priority for this message</dd> |
| <dd><code>timeToLive</code> - the message's lifetime (in milliseconds)</dd> |
| <dd><code>completionListener</code> - a <code>CompletionListener</code> to be notified when the send has completed</dd> |
| <dt><span class="throwsLabel">Throws:</span></dt> |
| <dd><code><a href="../../javax/jms/JMSException.html" title="class in javax.jms">JMSException</a></code> - if an internal error occurs</dd> |
| <dd><code><a href="../../javax/jms/MessageFormatException.html" title="class in javax.jms">MessageFormatException</a></code> - if an invalid message is specified.</dd> |
| <dd><code><a href="../../javax/jms/InvalidDestinationException.html" title="class in javax.jms">InvalidDestinationException</a></code> - if a client uses this method with an invalid destination.</dd> |
| <dd><code>java.lang.IllegalArgumentException</code> - if the specified <code>CompletionListener</code> is null</dd> |
| <dd><code>java.lang.UnsupportedOperationException</code> - if a client uses this method with a <code>MessageProducer</code> that |
| specified a destination at creation time.</dd> |
| <dt><span class="simpleTagLabel">Since:</span></dt> |
| <dd>JMS 2.0</dd> |
| <dt><span class="seeLabel">See Also:</span></dt> |
| <dd><a href="../../javax/jms/Session.html#createProducer-javax.jms.Destination-"><code>Session.createProducer(javax.jms.Destination)</code></a>, |
| <a href="../../javax/jms/CompletionListener.html" title="interface in javax.jms"><code>CompletionListener</code></a></dd> |
| </dl> |
| </li> |
| </ul> |
| </li> |
| </ul> |
| </li> |
| </ul> |
| </div> |
| </div> |
| <!-- ========= END OF CLASS DATA ========= --> |
| <!-- ======= START OF BOTTOM NAVBAR ====== --> |
| <div class="bottomNav"><a name="navbar.bottom"> |
| <!-- --> |
| </a> |
| <div class="skipNav"><a href="#skip.navbar.bottom" title="Skip navigation links">Skip navigation links</a></div> |
| <a name="navbar.bottom.firstrow"> |
| <!-- --> |
| </a> |
| <ul class="navList" title="Navigation"> |
| <li><a href="../../overview-summary.html">Overview</a></li> |
| <li><a href="package-summary.html">Package</a></li> |
| <li class="navBarCell1Rev">Class</li> |
| <li><a href="package-tree.html">Tree</a></li> |
| <li><a href="../../deprecated-list.html">Deprecated</a></li> |
| <li><a href="../../index-all.html">Index</a></li> |
| <li><a href="../../help-doc.html">Help</a></li> |
| </ul> |
| </div> |
| <div class="subNav"> |
| <ul class="navList"> |
| <li><a href="../../javax/jms/MessageNotWriteableRuntimeException.html" title="class in javax.jms"><span class="typeNameLink">Prev Class</span></a></li> |
| <li><a href="../../javax/jms/ObjectMessage.html" title="interface in javax.jms"><span class="typeNameLink">Next Class</span></a></li> |
| </ul> |
| <ul class="navList"> |
| <li><a href="../../index.html?javax/jms/MessageProducer.html" target="_top">Frames</a></li> |
| <li><a href="MessageProducer.html" target="_top">No Frames</a></li> |
| </ul> |
| <ul class="navList" id="allclasses_navbar_bottom"> |
| <li><a href="../../allclasses-noframe.html">All Classes</a></li> |
| </ul> |
| <div> |
| <script type="text/javascript"><!-- |
| allClassesLink = document.getElementById("allclasses_navbar_bottom"); |
| if(window==top) { |
| allClassesLink.style.display = "block"; |
| } |
| else { |
| allClassesLink.style.display = "none"; |
| } |
| //--> |
| </script> |
| </div> |
| <div> |
| <ul class="subNavList"> |
| <li>Summary: </li> |
| <li>Nested | </li> |
| <li>Field | </li> |
| <li>Constr | </li> |
| <li><a href="#method.summary">Method</a></li> |
| </ul> |
| <ul class="subNavList"> |
| <li>Detail: </li> |
| <li>Field | </li> |
| <li>Constr | </li> |
| <li><a href="#method.detail">Method</a></li> |
| </ul> |
| </div> |
| <a name="skip.navbar.bottom"> |
| <!-- --> |
| </a></div> |
| <!-- ======== END OF BOTTOM NAVBAR ======= --> |
| </body> |
| </html> |
