| <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd"> |
| <!-- NewPage --> |
| <html lang="en"> |
| <head> |
| <title>Connection</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="Connection"; |
| } |
| } |
| 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}; |
| 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/CompletionListener.html" title="interface in javax.jms"><span class="typeNameLink">Prev Class</span></a></li> |
| <li><a href="../../javax/jms/ConnectionConsumer.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/Connection.html" target="_top">Frames</a></li> |
| <li><a href="Connection.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 Connection" class="title">Interface Connection</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/QueueConnection.html" title="interface in javax.jms">QueueConnection</a>, <a href="../../javax/jms/TopicConnection.html" title="interface in javax.jms">TopicConnection</a>, <a href="../../javax/jms/XAConnection.html" title="interface in javax.jms">XAConnection</a>, <a href="../../javax/jms/XAQueueConnection.html" title="interface in javax.jms">XAQueueConnection</a>, <a href="../../javax/jms/XATopicConnection.html" title="interface in javax.jms">XATopicConnection</a></dd> |
| </dl> |
| <dl> |
| <dt>All Known Implementing Classes:</dt> |
| <dd><a href="../../org/apache/openejb/resource/activemq/jms2/TomEEManagedConnectionProxy.html" title="class in org.apache.openejb.resource.activemq.jms2">TomEEManagedConnectionProxy</a></dd> |
| </dl> |
| <hr> |
| <br> |
| <pre>public interface <span class="typeNameLabel">Connection</span> |
| extends java.lang.AutoCloseable</pre> |
| <div class="block">A <code>Connection</code> object is a client's active connection to its JMS provider. It typically allocates provider |
| resources outside the Java virtual machine (JVM). |
| |
| <p> |
| Connections support concurrent use. |
| |
| <p> |
| A connection serves several purposes: |
| |
| <ul> |
| <li>It encapsulates an open connection with a JMS provider. It typically represents an open TCP/IP socket between a |
| client and the service provider software. |
| <li>Its creation is where client authentication takes place. |
| <li>It can specify a unique client identifier. |
| <li>It provides a <code>ConnectionMetaData</code> object. |
| <li>It supports an optional <code>ExceptionListener</code> object. |
| </ul> |
| |
| <p> |
| Because the creation of a connection involves setting up authentication and communication, a connection is a |
| relatively heavyweight object. Most clients will do all their messaging with a single connection. Other more advanced |
| applications may use several connections. The JMS API does not architect a reason for using multiple connections; |
| however, there may be operational reasons for doing so. |
| |
| <p> |
| A JMS client typically creates a connection, one or more sessions, and a number of message producers and consumers. |
| When a connection is created, it is in stopped mode. That means that no messages are being delivered. |
| |
| <p> |
| It is typical to leave the connection in stopped mode until setup is complete (that is, until all message consumers |
| have been created). At that point, the client calls the connection's <code>start</code> method, and messages begin |
| arriving at the connection's consumers. This setup convention minimizes any client confusion that may result from |
| asynchronous message delivery while the client is still in the process of setting itself up. |
| |
| <p> |
| A connection can be started immediately, and the setup can be done afterwards. Clients that do this must be prepared |
| to handle asynchronous message delivery while they are still in the process of setting up. |
| |
| <p> |
| A message producer can send messages while a connection is stopped.</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/ConnectionFactory.html" title="interface in javax.jms"><code>ConnectionFactory</code></a>, |
| <a href="../../javax/jms/QueueConnection.html" title="interface in javax.jms"><code>QueueConnection</code></a>, |
| <a href="../../javax/jms/TopicConnection.html" title="interface in javax.jms"><code>TopicConnection</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/Connection.html#close--">close</a></span>()</code> |
| <div class="block">Closes the connection.</div> |
| </td> |
| </tr> |
| <tr id="i1" class="rowColor"> |
| <td class="colFirst"><code><a href="../../javax/jms/ConnectionConsumer.html" title="interface in javax.jms">ConnectionConsumer</a></code></td> |
| <td class="colLast"><code><span class="memberNameLink"><a href="../../javax/jms/Connection.html#createConnectionConsumer-javax.jms.Destination-java.lang.String-javax.jms.ServerSessionPool-int-">createConnectionConsumer</a></span>(<a href="../../javax/jms/Destination.html" title="interface in javax.jms">Destination</a> destination, |
| java.lang.String messageSelector, |
| <a href="../../javax/jms/ServerSessionPool.html" title="interface in javax.jms">ServerSessionPool</a> sessionPool, |
| int maxMessages)</code> |
| <div class="block">Creates a connection consumer for this connection (optional operation) on the specific destination.</div> |
| </td> |
| </tr> |
| <tr id="i2" class="altColor"> |
| <td class="colFirst"><code><a href="../../javax/jms/ConnectionConsumer.html" title="interface in javax.jms">ConnectionConsumer</a></code></td> |
| <td class="colLast"><code><span class="memberNameLink"><a href="../../javax/jms/Connection.html#createDurableConnectionConsumer-javax.jms.Topic-java.lang.String-java.lang.String-javax.jms.ServerSessionPool-int-">createDurableConnectionConsumer</a></span>(<a href="../../javax/jms/Topic.html" title="interface in javax.jms">Topic</a> topic, |
| java.lang.String subscriptionName, |
| java.lang.String messageSelector, |
| <a href="../../javax/jms/ServerSessionPool.html" title="interface in javax.jms">ServerSessionPool</a> sessionPool, |
| int maxMessages)</code> |
| <div class="block">Creates a connection consumer for this connection (optional operation) on the specific topic using an unshared |
| durable subscription with the specified name.</div> |
| </td> |
| </tr> |
| <tr id="i3" class="rowColor"> |
| <td class="colFirst"><code><a href="../../javax/jms/Session.html" title="interface in javax.jms">Session</a></code></td> |
| <td class="colLast"><code><span class="memberNameLink"><a href="../../javax/jms/Connection.html#createSession--">createSession</a></span>()</code> |
| <div class="block">Creates a <code>Session</code> object, specifying no arguments.</div> |
| </td> |
| </tr> |
| <tr id="i4" class="altColor"> |
| <td class="colFirst"><code><a href="../../javax/jms/Session.html" title="interface in javax.jms">Session</a></code></td> |
| <td class="colLast"><code><span class="memberNameLink"><a href="../../javax/jms/Connection.html#createSession-boolean-int-">createSession</a></span>(boolean transacted, |
| int acknowledgeMode)</code> |
| <div class="block">Creates a <code>Session</code> object, specifying <code>transacted</code> and <code>acknowledgeMode</code>.</div> |
| </td> |
| </tr> |
| <tr id="i5" class="rowColor"> |
| <td class="colFirst"><code><a href="../../javax/jms/Session.html" title="interface in javax.jms">Session</a></code></td> |
| <td class="colLast"><code><span class="memberNameLink"><a href="../../javax/jms/Connection.html#createSession-int-">createSession</a></span>(int sessionMode)</code> |
| <div class="block">Creates a <code>Session</code> object, specifying <code>sessionMode</code>.</div> |
| </td> |
| </tr> |
| <tr id="i6" class="altColor"> |
| <td class="colFirst"><code><a href="../../javax/jms/ConnectionConsumer.html" title="interface in javax.jms">ConnectionConsumer</a></code></td> |
| <td class="colLast"><code><span class="memberNameLink"><a href="../../javax/jms/Connection.html#createSharedConnectionConsumer-javax.jms.Topic-java.lang.String-java.lang.String-javax.jms.ServerSessionPool-int-">createSharedConnectionConsumer</a></span>(<a href="../../javax/jms/Topic.html" title="interface in javax.jms">Topic</a> topic, |
| java.lang.String subscriptionName, |
| java.lang.String messageSelector, |
| <a href="../../javax/jms/ServerSessionPool.html" title="interface in javax.jms">ServerSessionPool</a> sessionPool, |
| int maxMessages)</code> |
| <div class="block">Creates a connection consumer for this connection (optional operation) on the specific topic using a shared |
| non-durable subscription with the specified name.</div> |
| </td> |
| </tr> |
| <tr id="i7" class="rowColor"> |
| <td class="colFirst"><code><a href="../../javax/jms/ConnectionConsumer.html" title="interface in javax.jms">ConnectionConsumer</a></code></td> |
| <td class="colLast"><code><span class="memberNameLink"><a href="../../javax/jms/Connection.html#createSharedDurableConnectionConsumer-javax.jms.Topic-java.lang.String-java.lang.String-javax.jms.ServerSessionPool-int-">createSharedDurableConnectionConsumer</a></span>(<a href="../../javax/jms/Topic.html" title="interface in javax.jms">Topic</a> topic, |
| java.lang.String subscriptionName, |
| java.lang.String messageSelector, |
| <a href="../../javax/jms/ServerSessionPool.html" title="interface in javax.jms">ServerSessionPool</a> sessionPool, |
| int maxMessages)</code> |
| <div class="block">Creates a connection consumer for this connection (optional operation) on the specific topic using a shared durable |
| subscription with the specified name.</div> |
| </td> |
| </tr> |
| <tr id="i8" class="altColor"> |
| <td class="colFirst"><code>java.lang.String</code></td> |
| <td class="colLast"><code><span class="memberNameLink"><a href="../../javax/jms/Connection.html#getClientID--">getClientID</a></span>()</code> |
| <div class="block">Gets the client identifier for this connection.</div> |
| </td> |
| </tr> |
| <tr id="i9" class="rowColor"> |
| <td class="colFirst"><code><a href="../../javax/jms/ExceptionListener.html" title="interface in javax.jms">ExceptionListener</a></code></td> |
| <td class="colLast"><code><span class="memberNameLink"><a href="../../javax/jms/Connection.html#getExceptionListener--">getExceptionListener</a></span>()</code> |
| <div class="block">Gets the <code>ExceptionListener</code> object for this connection.</div> |
| </td> |
| </tr> |
| <tr id="i10" class="altColor"> |
| <td class="colFirst"><code><a href="../../javax/jms/ConnectionMetaData.html" title="interface in javax.jms">ConnectionMetaData</a></code></td> |
| <td class="colLast"><code><span class="memberNameLink"><a href="../../javax/jms/Connection.html#getMetaData--">getMetaData</a></span>()</code> |
| <div class="block">Gets the metadata for this connection.</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/Connection.html#setClientID-java.lang.String-">setClientID</a></span>(java.lang.String clientID)</code> |
| <div class="block">Sets the client identifier for this connection.</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/Connection.html#setExceptionListener-javax.jms.ExceptionListener-">setExceptionListener</a></span>(<a href="../../javax/jms/ExceptionListener.html" title="interface in javax.jms">ExceptionListener</a> listener)</code> |
| <div class="block">Sets an exception listener for this connection.</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/Connection.html#start--">start</a></span>()</code> |
| <div class="block">Starts (or restarts) a connection's delivery of incoming messages.</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/Connection.html#stop--">stop</a></span>()</code> |
| <div class="block">Temporarily stops a connection's delivery of incoming messages.</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="createSession-boolean-int-"> |
| <!-- --> |
| </a> |
| <ul class="blockList"> |
| <li class="blockList"> |
| <h4>createSession</h4> |
| <pre><a href="../../javax/jms/Session.html" title="interface in javax.jms">Session</a> createSession(boolean transacted, |
| int acknowledgeMode) |
| throws <a href="../../javax/jms/JMSException.html" title="class in javax.jms">JMSException</a></pre> |
| <div class="block">Creates a <code>Session</code> object, specifying <code>transacted</code> and <code>acknowledgeMode</code>. |
| |
| <p> |
| This method has been superseded by the method <code>createSession(int sessionMode)</code> which specifies the same |
| information using a single argument, and by the method <code>createSession()</code> which is for use in a Java EE JTA |
| transaction. Applications should consider using those methods instead of this one. |
| |
| <p> |
| The effect of setting the <code>transacted</code> and <code>acknowledgeMode</code> arguments depends on whether this method is |
| called in a Java SE environment, in the Java EE application client container, or in the Java EE web or EJB container. |
| If this method is called in the Java EE web or EJB container then the effect of setting the transacted} and |
| <code>acknowledgeMode</code> arguments also depends on whether or not there is an active JTA transaction in progress. |
| |
| <p> |
| In a <b>Java SE environment</b> or in <b>the Java EE application client container</b>: |
| <ul> |
| <li>If <code>transacted</code> is set to <code>true</code> then the session will use a local transaction which may subsequently |
| be committed or rolled back by calling the session's <code>commit</code> or <code>rollback</code> methods. The argument |
| <code>acknowledgeMode</code> is ignored. |
| <li>If <code>transacted</code> is set to <code>false</code> then the session will be non-transacted. In this case the argument |
| <code>acknowledgeMode</code> is used to specify how messages received by this session will be acknowledged. The permitted |
| values are <code>Session.CLIENT_ACKNOWLEDGE</code>, <code>Session.AUTO_ACKNOWLEDGE</code> and |
| <code>Session.DUPS_OK_ACKNOWLEDGE</code>. For a definition of the meaning of these acknowledgement modes see the links |
| below. |
| </ul> |
| |
| <p> |
| In a <b>Java EE web or EJB container, when there is an active JTA transaction in progress</b>: |
| <ul> |
| <li>Both arguments <code>transacted</code> and <code>acknowledgeMode</code> are ignored. The session will participate in the |
| JTA transaction and will be committed or rolled back when that transaction is committed or rolled back, not by |
| calling the session's <code>commit</code> or <code>rollback</code> methods. Since both arguments are ignored, developers are |
| recommended to use <code>createSession()</code>, which has no arguments, instead of this method. |
| </ul> |
| |
| <p> |
| In the <b>Java EE web or EJB container, when there is no active JTA transaction in progress</b>: |
| <ul> |
| <li>If <code>transacted</code> is set to false and <code>acknowledgeMode</code> is set to <code>JMSContext.AUTO_ACKNOWLEDGE</code> |
| or <code>Session.DUPS_OK_ACKNOWLEDGE</code> then the session will be non-transacted and messages will be acknowledged |
| according to the value of <code>acknowledgeMode</code>. |
| <li>If <code>transacted</code> is set to false and <code>acknowledgeMode</code> is set to <code>JMSContext.CLIENT_ACKNOWLEDGE</code> |
| then the JMS provider is recommended to ignore the specified parameters and instead provide a non-transacted, |
| auto-acknowledged session. However the JMS provider may alternatively provide a non-transacted session with client |
| acknowledgement. |
| <li>If <code>transacted</code> is set to true, then the JMS provider is recommended to ignore the specified parameters and |
| instead provide a non-transacted, auto-acknowledged session. However the JMS provider may alternatively provide a |
| local transacted session. |
| <li>Applications are recommended to set <code>transacted</code> to false and <code>acknowledgeMode</code> to |
| <code>JMSContext.AUTO_ACKNOWLEDGE</code> or <code>Session.DUPS_OK_ACKNOWLEDGE</code> since since applications which set |
| <code>transacted</code> to false and set <code>acknowledgeMode</code> to <code>JMSContext.CLIENT_ACKNOWLEDGE</code>, or which set |
| <code>transacted</code> to true, may not be portable. |
| </ul> |
| |
| <p> |
| Applications running in the Java EE web and EJB containers must not attempt to create more than one active (not |
| closed) <code>Session</code> object per connection. If this method is called in a Java EE web or EJB container when an |
| active <code>Session</code> object already exists for this connection then a <code>JMSException</code> may be thrown.</div> |
| <dl> |
| <dt><span class="paramLabel">Parameters:</span></dt> |
| <dd><code>transacted</code> - indicates whether the session will use a local transaction, except in the cases described above |
| when this value is ignored..</dd> |
| <dd><code>acknowledgeMode</code> - when transacted is false, indicates how messages received by the session will be acknowledged, |
| except in the cases described above when this value is ignored.</dd> |
| <dt><span class="returnLabel">Returns:</span></dt> |
| <dd>a newly created session</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 <code>Connection</code> object fails to create a session due to |
| <ul> |
| <li>some internal error, |
| <li>lack of support for the specific transaction and acknowledgement mode, or |
| <li>because this method is being called in a Java EE web or EJB application and an active session already exists for |
| this connection. |
| </ul></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#AUTO_ACKNOWLEDGE"><code>Session.AUTO_ACKNOWLEDGE</code></a>, |
| <a href="../../javax/jms/Session.html#CLIENT_ACKNOWLEDGE"><code>Session.CLIENT_ACKNOWLEDGE</code></a>, |
| <a href="../../javax/jms/Session.html#DUPS_OK_ACKNOWLEDGE"><code>Session.DUPS_OK_ACKNOWLEDGE</code></a>, |
| <a href="../../javax/jms/Connection.html#createSession-int-"><code>createSession(int)</code></a>, |
| <a href="../../javax/jms/Connection.html#createSession--"><code>createSession()</code></a></dd> |
| </dl> |
| </li> |
| </ul> |
| <a name="createSession-int-"> |
| <!-- --> |
| </a> |
| <ul class="blockList"> |
| <li class="blockList"> |
| <h4>createSession</h4> |
| <pre><a href="../../javax/jms/Session.html" title="interface in javax.jms">Session</a> createSession(int sessionMode) |
| throws <a href="../../javax/jms/JMSException.html" title="class in javax.jms">JMSException</a></pre> |
| <div class="block">Creates a <code>Session</code> object, specifying <code>sessionMode</code>. |
| |
| <p> |
| The effect of setting the <code>sessionMode</code> argument depends on whether this method is called in a Java SE |
| environment, in the Java EE application client container, or in the Java EE web or EJB container. If this method is |
| called in the Java EE web or EJB container then the effect of setting the <code>sessionMode</code> argument also depends |
| on whether or not there is an active JTA transaction in progress. |
| |
| <p> |
| In a <b>Java SE environment</b> or in <b>the Java EE application client container</b>: |
| <ul> |
| <li>If <code>sessionMode</code> is set to <code>Session.SESSION_TRANSACTED</code> then the session will use a local transaction |
| which may subsequently be committed or rolled back by calling the session's <code>commit</code> or <code>rollback</code> |
| methods. |
| <li>If <code>sessionMode</code> is set to any of <code>Session.CLIENT_ACKNOWLEDGE</code>, <code>Session.AUTO_ACKNOWLEDGE</code> or |
| <code>Session.DUPS_OK_ACKNOWLEDGE</code>. then the session will be non-transacted and messages received by this session |
| will be acknowledged according to the value of <code>sessionMode</code>. For a definition of the meaning of these |
| acknowledgement modes see the links below. |
| </ul> |
| |
| <p> |
| In a <b>Java EE web or EJB container, when there is an active JTA transaction in progress</b>: |
| <ul> |
| <li>The argument <code>sessionMode</code> is ignored. The session will participate in the JTA transaction and will be |
| committed or rolled back when that transaction is committed or rolled back, not by calling the session's |
| <code>commit</code> or <code>rollback</code> methods. Since the argument is ignored, developers are recommended to use |
| <code>createSession()</code>, which has no arguments, instead of this method. |
| </ul> |
| |
| <p> |
| In the <b>Java EE web or EJB container, when there is no active JTA transaction in progress</b>: |
| <ul> |
| <li>If <code>sessionMode</code> is set to <code>Session.AUTO_ACKNOWLEDGE</code> or <code>Session.DUPS_OK_ACKNOWLEDGE</code> then the |
| session will be non-transacted and messages will be acknowledged according to the value of <code>sessionMode</code>. |
| <li>If <code>sessionMode</code> is set to <code>Session.CLIENT_ACKNOWLEDGE</code> then the JMS provider is recommended to |
| ignore the specified parameter and instead provide a non-transacted, auto-acknowledged session. However the JMS |
| provider may alternatively provide a non-transacted session with client acknowledgement. |
| <li>If <code>sessionMode</code> is set to <code>Session.SESSION_TRANSACTED</code>, then the JMS provider is recommended to |
| ignore the specified parameter and instead provide a non-transacted, auto-acknowledged session. However the JMS |
| provider may alternatively provide a local transacted session. |
| <li>Applications are recommended to use only the values <code>Session.AUTO_ACKNOWLEDGE</code> and |
| <code>Session.DUPS_OK_ACKNOWLEDGE</code> since applications which use <code>Session.CLIENT_ACKNOWLEDGE</code> or |
| <code>Session.SESSION_TRANSACTED</code> may not be portable. |
| </ul> |
| |
| <p> |
| Applications running in the Java EE web and EJB containers must not attempt to create more than one active (not |
| closed) <code>Session</code> object per connection. If this method is called in a Java EE web or EJB container when an |
| active <code>Session</code> object already exists for this connection then a <code>JMSException</code> may be thrown.</div> |
| <dl> |
| <dt><span class="paramLabel">Parameters:</span></dt> |
| <dd><code>sessionMode</code> - specifies the session mode that will be used, except in the cases described above when this value |
| is ignored. Legal values are <code>JMSContext.SESSION_TRANSACTED</code>, <code>JMSContext.CLIENT_ACKNOWLEDGE</code>, |
| <code>JMSContext.AUTO_ACKNOWLEDGE</code> and <code>JMSContext.DUPS_OK_ACKNOWLEDGE</code>.</dd> |
| <dt><span class="returnLabel">Returns:</span></dt> |
| <dd>a newly created session</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 <code>Connection</code> object fails to create a session due to |
| <ul> |
| <li>some internal error, |
| <li>lack of support for the specific transaction and acknowledgement mode, or |
| <li>because this method is being called in a Java EE web or EJB application and an active session already exists for |
| this connection. |
| </ul></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#SESSION_TRANSACTED"><code>Session.SESSION_TRANSACTED</code></a>, |
| <a href="../../javax/jms/Session.html#AUTO_ACKNOWLEDGE"><code>Session.AUTO_ACKNOWLEDGE</code></a>, |
| <a href="../../javax/jms/Session.html#CLIENT_ACKNOWLEDGE"><code>Session.CLIENT_ACKNOWLEDGE</code></a>, |
| <a href="../../javax/jms/Session.html#DUPS_OK_ACKNOWLEDGE"><code>Session.DUPS_OK_ACKNOWLEDGE</code></a>, |
| <a href="../../javax/jms/Connection.html#createSession-boolean-int-"><code>createSession(boolean, int)</code></a>, |
| <a href="../../javax/jms/Connection.html#createSession--"><code>createSession()</code></a></dd> |
| </dl> |
| </li> |
| </ul> |
| <a name="createSession--"> |
| <!-- --> |
| </a> |
| <ul class="blockList"> |
| <li class="blockList"> |
| <h4>createSession</h4> |
| <pre><a href="../../javax/jms/Session.html" title="interface in javax.jms">Session</a> createSession() |
| throws <a href="../../javax/jms/JMSException.html" title="class in javax.jms">JMSException</a></pre> |
| <div class="block">Creates a <code>Session</code> object, specifying no arguments. |
| |
| <p> |
| The behaviour of the session that is created depends on whether this method is called in a Java SE environment, in |
| the Java EE application client container, or in the Java EE web or EJB container. If this method is called in the |
| Java EE web or EJB container then the behaviour of the session also depends on whether or not there is an active JTA |
| transaction in progress. |
| |
| <p> |
| In a <b>Java SE environment</b> or in <b>the Java EE application client container</b>: |
| <ul> |
| <li>The session will be non-transacted and received messages will be acknowledged automatically using an |
| acknowledgement mode of <code>Session.AUTO_ACKNOWLEDGE</code> For a definition of the meaning of this acknowledgement mode |
| see the link below. |
| </ul> |
| |
| <p> |
| In a <b>Java EE web or EJB container, when there is an active JTA transaction in progress</b>: |
| <ul> |
| <li>The session will participate in the JTA transaction and will be committed or rolled back when that transaction is |
| committed or rolled back, not by calling the session's <code>commit</code> or <code>rollback</code> methods. |
| </ul> |
| <p> |
| In the <b>Java EE web or EJB container, when there is no active JTA transaction in progress</b>: |
| <ul> |
| <li>The session will be non-transacted and received messages will be acknowledged automatically using an |
| acknowledgement mode of <code>Session.AUTO_ACKNOWLEDGE</code> For a definition of the meaning of this acknowledgement mode |
| see the link below. |
| </ul> |
| |
| <p> |
| Applications running in the Java EE web and EJB containers must not attempt to create more than one active (not |
| closed) <code>Session</code> object per connection. If this method is called in a Java EE web or EJB container when an |
| active <code>Session</code> object already exists for this connection then a <code>JMSException</code> may be thrown.</div> |
| <dl> |
| <dt><span class="returnLabel">Returns:</span></dt> |
| <dd>a newly created session</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 <code>Connection</code> object fails to create a session due to |
| <ul> |
| <li>some internal error or |
| <li>because this method is being called in a Java EE web or EJB application and an active session already exists for |
| this connection. |
| </ul></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#AUTO_ACKNOWLEDGE"><code>Session.AUTO_ACKNOWLEDGE</code></a>, |
| <a href="../../javax/jms/Connection.html#createSession-boolean-int-"><code>createSession(boolean, int)</code></a>, |
| <a href="../../javax/jms/Connection.html#createSession-int-"><code>createSession(int)</code></a></dd> |
| </dl> |
| </li> |
| </ul> |
| <a name="getClientID--"> |
| <!-- --> |
| </a> |
| <ul class="blockList"> |
| <li class="blockList"> |
| <h4>getClientID</h4> |
| <pre>java.lang.String getClientID() |
| throws <a href="../../javax/jms/JMSException.html" title="class in javax.jms">JMSException</a></pre> |
| <div class="block">Gets the client identifier for this connection. |
| |
| <p> |
| This value is specific to the JMS provider. It is either preconfigured by an administrator in a |
| <code>ConnectionFactory</code> object or assigned dynamically by the application by calling the <code>setClientID</code> |
| method.</div> |
| <dl> |
| <dt><span class="returnLabel">Returns:</span></dt> |
| <dd>the unique client identifier</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 return the client ID for this connection due to some internal |
| error.</dd> |
| </dl> |
| </li> |
| </ul> |
| <a name="setClientID-java.lang.String-"> |
| <!-- --> |
| </a> |
| <ul class="blockList"> |
| <li class="blockList"> |
| <h4>setClientID</h4> |
| <pre>void setClientID(java.lang.String clientID) |
| throws <a href="../../javax/jms/JMSException.html" title="class in javax.jms">JMSException</a></pre> |
| <div class="block">Sets the client identifier for this connection. |
| |
| <p> |
| The preferred way to assign a JMS client's client identifier is for it to be configured in a client-specific |
| <code>ConnectionFactory</code> object and transparently assigned to the <code>Connection</code> object it creates. |
| |
| <p> |
| Alternatively, a client can set a connection's client identifier using a provider-specific value. The facility to set |
| a connection's client identifier explicitly is not a mechanism for overriding the identifier that has been |
| administratively configured. It is provided for the case where no administratively specified identifier exists. If |
| one does exist, an attempt to change it by setting it must throw an <code>IllegalStateException</code>. If a client sets |
| the client identifier explicitly, it must do so immediately after it creates the connection and before any other |
| action on the connection is taken. After this point, setting the client identifier is a programming error that should |
| throw an <code>IllegalStateException</code>. |
| |
| <p> |
| The purpose of the client identifier is to associate a connection and its objects with a state maintained on behalf |
| of the client by a provider. The only such state identified by the JMS API is that required to support durable |
| subscriptions. |
| |
| <p> |
| If another connection with the same <code>clientID</code> is already running when this method is called, the JMS provider |
| should detect the duplicate ID and throw an <code>InvalidClientIDException</code>. |
| <p> |
| This method must not be used in a Java EE web or EJB application. Doing so may cause a <code>JMSException</code> to be |
| thrown though this is not guaranteed.</div> |
| <dl> |
| <dt><span class="paramLabel">Parameters:</span></dt> |
| <dd><code>clientID</code> - the unique client identifier</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 client ID for the the connection for one of the |
| following reasons: |
| <ul> |
| <li>an internal error has occurred or |
| <li>this method has been called in a Java EE web or EJB application (though it is not guaranteed that an exception is |
| thrown in this case) |
| </ul></dd> |
| <dd><code><a href="../../javax/jms/InvalidClientIDException.html" title="class in javax.jms">InvalidClientIDException</a></code> - if the JMS client specifies an invalid or duplicate client ID.</dd> |
| <dd><code><a href="../../javax/jms/IllegalStateException.html" title="class in javax.jms">IllegalStateException</a></code> - if the JMS client attempts to set a connection's client ID at the wrong time or when |
| it has been administratively configured.</dd> |
| </dl> |
| </li> |
| </ul> |
| <a name="getMetaData--"> |
| <!-- --> |
| </a> |
| <ul class="blockList"> |
| <li class="blockList"> |
| <h4>getMetaData</h4> |
| <pre><a href="../../javax/jms/ConnectionMetaData.html" title="interface in javax.jms">ConnectionMetaData</a> getMetaData() |
| throws <a href="../../javax/jms/JMSException.html" title="class in javax.jms">JMSException</a></pre> |
| <div class="block">Gets the metadata for this connection.</div> |
| <dl> |
| <dt><span class="returnLabel">Returns:</span></dt> |
| <dd>the connection metadata</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 connection metadata for this connection.</dd> |
| <dt><span class="seeLabel">See Also:</span></dt> |
| <dd><a href="../../javax/jms/ConnectionMetaData.html" title="interface in javax.jms"><code>ConnectionMetaData</code></a></dd> |
| </dl> |
| </li> |
| </ul> |
| <a name="getExceptionListener--"> |
| <!-- --> |
| </a> |
| <ul class="blockList"> |
| <li class="blockList"> |
| <h4>getExceptionListener</h4> |
| <pre><a href="../../javax/jms/ExceptionListener.html" title="interface in javax.jms">ExceptionListener</a> getExceptionListener() |
| throws <a href="../../javax/jms/JMSException.html" title="class in javax.jms">JMSException</a></pre> |
| <div class="block">Gets the <code>ExceptionListener</code> object for this connection. Not every <code>Connection</code> has an |
| <code>ExceptionListener</code> associated with it.</div> |
| <dl> |
| <dt><span class="returnLabel">Returns:</span></dt> |
| <dd>the <code>ExceptionListener</code> for this connection, or null. if no <code>ExceptionListener</code> is associated |
| with this connection.</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 <code>ExceptionListener</code> for this connection.</dd> |
| <dt><span class="seeLabel">See Also:</span></dt> |
| <dd><a href="../../javax/jms/Connection.html#setExceptionListener-javax.jms.ExceptionListener-"><code>setExceptionListener(javax.jms.ExceptionListener)</code></a></dd> |
| </dl> |
| </li> |
| </ul> |
| <a name="setExceptionListener-javax.jms.ExceptionListener-"> |
| <!-- --> |
| </a> |
| <ul class="blockList"> |
| <li class="blockList"> |
| <h4>setExceptionListener</h4> |
| <pre>void setExceptionListener(<a href="../../javax/jms/ExceptionListener.html" title="interface in javax.jms">ExceptionListener</a> listener) |
| throws <a href="../../javax/jms/JMSException.html" title="class in javax.jms">JMSException</a></pre> |
| <div class="block">Sets an exception listener for this connection. |
| |
| <p> |
| If a JMS provider detects a serious problem with a connection, it informs the connection's <code>ExceptionListener</code>, |
| if one has been registered. It does this by calling the listener's <code>onException</code> method, passing it a |
| <code>JMSException</code> object describing the problem. |
| |
| <p> |
| An exception listener allows a client to be notified of a problem asynchronously. Some connections only consume |
| messages, so they would have no other way to learn their connection has failed. |
| |
| <p> |
| A connection serializes execution of its <code>ExceptionListener</code>. |
| |
| <p> |
| A JMS provider should attempt to resolve connection problems itself before it notifies the client of them. |
| <p> |
| This method must not be used in a Java EE web or EJB application. Doing so may cause a <code>JMSException</code> to be |
| thrown though this is not guaranteed.</div> |
| <dl> |
| <dt><span class="paramLabel">Parameters:</span></dt> |
| <dd><code>listener</code> - the exception listener</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 exception listener for one of the following reasons: |
| <ul> |
| <li>an internal error has occurred or |
| <li>this method has been called in a Java EE web or EJB application (though it is not guaranteed that an exception is |
| thrown in this case) |
| </ul></dd> |
| </dl> |
| </li> |
| </ul> |
| <a name="start--"> |
| <!-- --> |
| </a> |
| <ul class="blockList"> |
| <li class="blockList"> |
| <h4>start</h4> |
| <pre>void start() |
| throws <a href="../../javax/jms/JMSException.html" title="class in javax.jms">JMSException</a></pre> |
| <div class="block">Starts (or restarts) a connection's delivery of incoming messages. A call to <code>start</code> on a connection that has |
| already been started is ignored.</div> |
| <dl> |
| <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 start message delivery due to some internal error.</dd> |
| <dt><span class="seeLabel">See Also:</span></dt> |
| <dd><a href="../../javax/jms/Connection.html#stop--"><code>stop()</code></a></dd> |
| </dl> |
| </li> |
| </ul> |
| <a name="stop--"> |
| <!-- --> |
| </a> |
| <ul class="blockList"> |
| <li class="blockList"> |
| <h4>stop</h4> |
| <pre>void stop() |
| throws <a href="../../javax/jms/JMSException.html" title="class in javax.jms">JMSException</a></pre> |
| <div class="block">Temporarily stops a connection's delivery of incoming messages. Delivery can be restarted using the connection's |
| <code>start</code> method. When the connection is stopped, delivery to all the connection's message consumers is |
| inhibited: synchronous receives block, and messages are not delivered to message listeners. |
| |
| <p> |
| Stopping a connection has no effect on its ability to send messages. A call to <code>stop</code> on a connection that has |
| already been stopped is ignored. |
| |
| <p> |
| A call to <code>stop</code> must not return until delivery of messages has paused. This means that a client can rely on |
| the fact that none of its message listeners will be called and that all threads of control waiting for |
| <code>receive</code> calls to return will not return with a message until the connection is restarted. The receive timers |
| for a stopped connection continue to advance, so receives may time out while the connection is stopped. |
| |
| <p> |
| If message listeners are running when <code>stop</code> is invoked, the <code>stop</code> call must wait until all of them have |
| returned before it may return. While these message listeners are completing, they must have the full services of the |
| connection available to them. |
| <p> |
| However if the <code>stop</code> method is called from a message listener on its own connection, then it will either fail |
| and throw a <code>javax.jms.IllegalStateException</code>, or it will succeed and stop the connection, blocking until all |
| other message listeners that may have been running have returned. |
| <p> |
| Since two alternative behaviors are permitted in this case, applications should avoid calling <code>stop</code> from a |
| message listener on its own Connection because this is not portable. |
| <p> |
| For the avoidance of doubt, if an exception listener for this connection is running when <code>stop</code> is invoked, |
| there is no requirement for the <code>stop</code> call to wait until the exception listener has returned before it may |
| return. |
| <p> |
| This method must not be used in a Java EE web or EJB application. Doing so may cause a <code>JMSException</code> to be |
| thrown though this is not guaranteed.</div> |
| <dl> |
| <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>MessageListener</tt> on its own |
| <tt>Connection</tt></dd> |
| <dd><code><a href="../../javax/jms/JMSException.html" title="class in javax.jms">JMSException</a></code> - if the JMS provider fails to stop message delivery for one of the following reasons: |
| <ul> |
| <li>an internal error has occurred or |
| <li>this method has been called in a Java EE web or EJB application (though it is not guaranteed that an exception is |
| thrown in this case) |
| </ul></dd> |
| <dt><span class="seeLabel">See Also:</span></dt> |
| <dd><a href="../../javax/jms/Connection.html#start--"><code>start()</code></a></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 connection. |
| |
| <p> |
| Since a provider typically allocates significant resources outside the JVM on behalf of a connection, clients should |
| close these resources when they are not needed. Relying on garbage collection to eventually reclaim these resources |
| may not be timely enough. |
| |
| <p> |
| There is no need to close the sessions, producers, and consumers of a closed connection. |
| |
| <p> |
| Closing a connection causes all temporary destinations to be deleted. |
| |
| <p> |
| When this method is invoked, it should not return until message processing has been shut down in an orderly fashion. |
| This means that all message listeners that may have been running have returned, and that all pending receives have |
| returned. |
| |
| <p> |
| However if the close method is called from a message listener on its own connection, then it will either fail and |
| throw a <code>javax.jms.IllegalStateException</code>, or it will succeed and close the connection, blocking until all |
| other message listeners that may have been running have returned, and all pending receive calls have completed. If |
| close succeeds and the acknowledge mode of the session is set to <code>AUTO_ACKNOWLEDGE</code>, the current message will |
| still be acknowledged automatically when the <code>onMessage</code> call completes. Since two alternative behaviors are |
| permitted in this case, applications should avoid calling close from a message listener on its own connection because |
| this is not portable. |
| |
| <p> |
| A close terminates all pending message receives on the connection's sessions' consumers. The receives may return with |
| a message or with null, depending on whether there was a message available at the time of the close. If one or more |
| of the connection's sessions' message listeners is processing a message at the time when connection <code>close</code> is |
| invoked, all the facilities of the connection and its sessions must remain available to those listeners until they |
| return control to the JMS provider. |
| |
| <p> |
| This method must not return until any incomplete asynchronous send operations for this <tt>Connection</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> |
| For the avoidance of doubt, if an exception listener for this connection is running when <code>close</code> is invoked, |
| there is no requirement for the <code>close</code> call to wait until the exception listener has returned before it may |
| return. |
| |
| <p> |
| Closing a connection causes any of its sessions' transactions in progress to be rolled back. In the case where a |
| session's work is coordinated by an external transaction manager, a session's <code>commit</code> and <code>rollback</code> |
| methods are not used and the result of a closed session's work is determined later by the transaction manager. |
| Closing a connection does NOT force an acknowledgment of client-acknowledged sessions. |
| |
| <p> |
| A <tt>CompletionListener</tt> callback method must not call <tt>close</tt> on its own <tt>Connection</tt>. Doing so |
| will cause an <tt>IllegalStateException</tt> to be thrown. |
| <p> |
| Invoking the <code>acknowledge</code> method of a received message from a closed connection's session must throw an |
| <code>IllegalStateException</code>. Closing a closed connection must NOT throw an exception.</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> - <ul> |
| <li>this method has been called by a <tt>MessageListener |
| </tt> on its own <tt>Connection</tt></li> |
| <li>this method has been called by a <tt>CompletionListener</tt> callback method on its own <tt>Connection</tt></li> |
| </ul></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 connection due to some internal error. For example, a |
| failure to release resources or to close a socket connection can cause this exception to be thrown.</dd> |
| </dl> |
| </li> |
| </ul> |
| <a name="createConnectionConsumer-javax.jms.Destination-java.lang.String-javax.jms.ServerSessionPool-int-"> |
| <!-- --> |
| </a> |
| <ul class="blockList"> |
| <li class="blockList"> |
| <h4>createConnectionConsumer</h4> |
| <pre><a href="../../javax/jms/ConnectionConsumer.html" title="interface in javax.jms">ConnectionConsumer</a> createConnectionConsumer(<a href="../../javax/jms/Destination.html" title="interface in javax.jms">Destination</a> destination, |
| java.lang.String messageSelector, |
| <a href="../../javax/jms/ServerSessionPool.html" title="interface in javax.jms">ServerSessionPool</a> sessionPool, |
| int maxMessages) |
| throws <a href="../../javax/jms/JMSException.html" title="class in javax.jms">JMSException</a></pre> |
| <div class="block">Creates a connection consumer for this connection (optional operation) on the specific destination. |
| |
| <p> |
| This is an expert facility not used by ordinary JMS clients. |
| |
| <p> |
| This method must not be used in a Java EE web or EJB application. Doing so may cause a <code>JMSException</code> to be |
| thrown though this is not guaranteed.</div> |
| <dl> |
| <dt><span class="paramLabel">Parameters:</span></dt> |
| <dd><code>destination</code> - the destination to access</dd> |
| <dd><code>messageSelector</code> - only messages with properties matching the message selector expression are delivered. A value |
| of null or an empty string indicates that there is no message selector for the message consumer.</dd> |
| <dd><code>sessionPool</code> - the server session pool to associate with this connection consumer</dd> |
| <dd><code>maxMessages</code> - the maximum number of messages that can be assigned to a server session at one time</dd> |
| <dt><span class="returnLabel">Returns:</span></dt> |
| <dd>the connection consumer</dd> |
| <dt><span class="throwsLabel">Throws:</span></dt> |
| <dd><code><a href="../../javax/jms/InvalidDestinationException.html" title="class in javax.jms">InvalidDestinationException</a></code> - if an invalid destination is specified.</dd> |
| <dd><code><a href="../../javax/jms/InvalidSelectorException.html" title="class in javax.jms">InvalidSelectorException</a></code> - if the message selector is invalid.</dd> |
| <dd><code><a href="../../javax/jms/JMSException.html" title="class in javax.jms">JMSException</a></code> - if the <code>Connection</code> object fails to create a connection consumer for one of the |
| following reasons: |
| <ul> |
| <li>an internal error has occurred |
| <li>invalid arguments for <code>sessionPool</code> and <code>messageSelector</code> or |
| <li>this method has been called in a Java EE web or EJB application (though it is not guaranteed that an exception is |
| thrown in this case) |
| </ul></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/ConnectionConsumer.html" title="interface in javax.jms"><code>ConnectionConsumer</code></a></dd> |
| </dl> |
| </li> |
| </ul> |
| <a name="createSharedConnectionConsumer-javax.jms.Topic-java.lang.String-java.lang.String-javax.jms.ServerSessionPool-int-"> |
| <!-- --> |
| </a> |
| <ul class="blockList"> |
| <li class="blockList"> |
| <h4>createSharedConnectionConsumer</h4> |
| <pre><a href="../../javax/jms/ConnectionConsumer.html" title="interface in javax.jms">ConnectionConsumer</a> createSharedConnectionConsumer(<a href="../../javax/jms/Topic.html" title="interface in javax.jms">Topic</a> topic, |
| java.lang.String subscriptionName, |
| java.lang.String messageSelector, |
| <a href="../../javax/jms/ServerSessionPool.html" title="interface in javax.jms">ServerSessionPool</a> sessionPool, |
| int maxMessages) |
| throws <a href="../../javax/jms/JMSException.html" title="class in javax.jms">JMSException</a></pre> |
| <div class="block">Creates a connection consumer for this connection (optional operation) on the specific topic using a shared |
| non-durable subscription with the specified name. |
| |
| <p> |
| This is an expert facility not used by ordinary JMS clients. |
| |
| <p> |
| This method must not be used in a Java EE web or EJB application. Doing so may cause a <code>JMSException</code> to be |
| thrown though this is not guaranteed.</div> |
| <dl> |
| <dt><span class="paramLabel">Parameters:</span></dt> |
| <dd><code>topic</code> - the topic to access</dd> |
| <dd><code>subscriptionName</code> - the name used to identify the shared non-durable subscription</dd> |
| <dd><code>messageSelector</code> - only messages with properties matching the message selector expression are delivered. A value |
| of null or an empty string indicates that there is no message selector for the message consumer.</dd> |
| <dd><code>sessionPool</code> - the server session pool to associate with this connection consumer</dd> |
| <dd><code>maxMessages</code> - the maximum number of messages that can be assigned to a server session at one time</dd> |
| <dt><span class="returnLabel">Returns:</span></dt> |
| <dd>the connection consumer</dd> |
| <dt><span class="throwsLabel">Throws:</span></dt> |
| <dd><code><a href="../../javax/jms/IllegalStateException.html" title="class in javax.jms">IllegalStateException</a></code> - if called on a <code>QueueConnection</code></dd> |
| <dd><code><a href="../../javax/jms/InvalidDestinationException.html" title="class in javax.jms">InvalidDestinationException</a></code> - if an invalid destination is specified.</dd> |
| <dd><code><a href="../../javax/jms/InvalidSelectorException.html" title="class in javax.jms">InvalidSelectorException</a></code> - if the message selector is invalid.</dd> |
| <dd><code><a href="../../javax/jms/JMSException.html" title="class in javax.jms">JMSException</a></code> - if the <code>Connection</code> object fails to create a connection consumer for one of the |
| following reasons: |
| <ul> |
| <li>an internal error has occurred |
| <li>invalid arguments for <code>sessionPool</code> and <code>messageSelector</code> or |
| <li>this method has been called in a Java EE web or EJB application (though it is not guaranteed that an exception is |
| thrown in this case) |
| </ul></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/ConnectionConsumer.html" title="interface in javax.jms"><code>ConnectionConsumer</code></a></dd> |
| </dl> |
| </li> |
| </ul> |
| <a name="createDurableConnectionConsumer-javax.jms.Topic-java.lang.String-java.lang.String-javax.jms.ServerSessionPool-int-"> |
| <!-- --> |
| </a> |
| <ul class="blockList"> |
| <li class="blockList"> |
| <h4>createDurableConnectionConsumer</h4> |
| <pre><a href="../../javax/jms/ConnectionConsumer.html" title="interface in javax.jms">ConnectionConsumer</a> createDurableConnectionConsumer(<a href="../../javax/jms/Topic.html" title="interface in javax.jms">Topic</a> topic, |
| java.lang.String subscriptionName, |
| java.lang.String messageSelector, |
| <a href="../../javax/jms/ServerSessionPool.html" title="interface in javax.jms">ServerSessionPool</a> sessionPool, |
| int maxMessages) |
| throws <a href="../../javax/jms/JMSException.html" title="class in javax.jms">JMSException</a></pre> |
| <div class="block">Creates a connection consumer for this connection (optional operation) on the specific topic using an unshared |
| durable subscription with the specified name. |
| |
| <p> |
| This is an expert facility not used by ordinary JMS clients. |
| |
| <p> |
| This method must not be used in a Java EE web or EJB application. Doing so may cause a <code>JMSException</code> to be |
| thrown though this is not guaranteed.</div> |
| <dl> |
| <dt><span class="paramLabel">Parameters:</span></dt> |
| <dd><code>topic</code> - topic to access</dd> |
| <dd><code>subscriptionName</code> - the name used to identify the unshared durable subscription</dd> |
| <dd><code>messageSelector</code> - only messages with properties matching the message selector expression are delivered. A value |
| of null or an empty string indicates that there is no message selector for the message consumer.</dd> |
| <dd><code>sessionPool</code> - the server session pool to associate with this durable connection consumer</dd> |
| <dd><code>maxMessages</code> - the maximum number of messages that can be assigned to a server session at one time</dd> |
| <dt><span class="returnLabel">Returns:</span></dt> |
| <dd>the durable connection consumer</dd> |
| <dt><span class="throwsLabel">Throws:</span></dt> |
| <dd><code><a href="../../javax/jms/IllegalStateException.html" title="class in javax.jms">IllegalStateException</a></code> - if called on a <code>QueueConnection</code></dd> |
| <dd><code><a href="../../javax/jms/InvalidDestinationException.html" title="class in javax.jms">InvalidDestinationException</a></code> - if an invalid destination is specified.</dd> |
| <dd><code><a href="../../javax/jms/InvalidSelectorException.html" title="class in javax.jms">InvalidSelectorException</a></code> - if the message selector is invalid.</dd> |
| <dd><code><a href="../../javax/jms/JMSException.html" title="class in javax.jms">JMSException</a></code> - if the <code>Connection</code> object fails to create a connection consumer for one of the |
| following reasons: |
| <ul> |
| <li>an internal error has occurred |
| <li>invalid arguments for <code>sessionPool</code> and <code>messageSelector</code> or |
| <li>this method has been called in a Java EE web or EJB application (though it is not guaranteed that an exception is |
| thrown in this case) |
| </ul></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/ConnectionConsumer.html" title="interface in javax.jms"><code>ConnectionConsumer</code></a></dd> |
| </dl> |
| </li> |
| </ul> |
| <a name="createSharedDurableConnectionConsumer-javax.jms.Topic-java.lang.String-java.lang.String-javax.jms.ServerSessionPool-int-"> |
| <!-- --> |
| </a> |
| <ul class="blockListLast"> |
| <li class="blockList"> |
| <h4>createSharedDurableConnectionConsumer</h4> |
| <pre><a href="../../javax/jms/ConnectionConsumer.html" title="interface in javax.jms">ConnectionConsumer</a> createSharedDurableConnectionConsumer(<a href="../../javax/jms/Topic.html" title="interface in javax.jms">Topic</a> topic, |
| java.lang.String subscriptionName, |
| java.lang.String messageSelector, |
| <a href="../../javax/jms/ServerSessionPool.html" title="interface in javax.jms">ServerSessionPool</a> sessionPool, |
| int maxMessages) |
| throws <a href="../../javax/jms/JMSException.html" title="class in javax.jms">JMSException</a></pre> |
| <div class="block">Creates a connection consumer for this connection (optional operation) on the specific topic using a shared durable |
| subscription with the specified name. |
| |
| <p> |
| This is an expert facility not used by ordinary JMS clients. |
| |
| <p> |
| This method must not be used in a Java EE web or EJB application. Doing so may cause a <code>JMSException</code> to be |
| thrown though this is not guaranteed.</div> |
| <dl> |
| <dt><span class="paramLabel">Parameters:</span></dt> |
| <dd><code>topic</code> - topic to access</dd> |
| <dd><code>subscriptionName</code> - the name used to identify the shared durable subscription</dd> |
| <dd><code>messageSelector</code> - only messages with properties matching the message selector expression are delivered. A value |
| of null or an empty string indicates that there is no message selector for the message consumer.</dd> |
| <dd><code>sessionPool</code> - the server session pool to associate with this durable connection consumer</dd> |
| <dd><code>maxMessages</code> - the maximum number of messages that can be assigned to a server session at one time</dd> |
| <dt><span class="returnLabel">Returns:</span></dt> |
| <dd>the durable connection consumer</dd> |
| <dt><span class="throwsLabel">Throws:</span></dt> |
| <dd><code><a href="../../javax/jms/IllegalStateException.html" title="class in javax.jms">IllegalStateException</a></code> - if called on a <code>QueueConnection</code></dd> |
| <dd><code><a href="../../javax/jms/InvalidDestinationException.html" title="class in javax.jms">InvalidDestinationException</a></code> - if an invalid destination is specified.</dd> |
| <dd><code><a href="../../javax/jms/InvalidSelectorException.html" title="class in javax.jms">InvalidSelectorException</a></code> - if the message selector is invalid.</dd> |
| <dd><code><a href="../../javax/jms/JMSException.html" title="class in javax.jms">JMSException</a></code> - if the <code>Connection</code> object fails to create a connection consumer for one of the |
| following reasons: |
| <ul> |
| <li>an internal error has occurred |
| <li>invalid arguments for <code>sessionPool</code> and <code>messageSelector</code> or |
| <li>this method has been called in a Java EE web or EJB application (though it is not guaranteed that an exception is |
| thrown in this case) |
| </ul></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/ConnectionConsumer.html" title="interface in javax.jms"><code>ConnectionConsumer</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/CompletionListener.html" title="interface in javax.jms"><span class="typeNameLink">Prev Class</span></a></li> |
| <li><a href="../../javax/jms/ConnectionConsumer.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/Connection.html" target="_top">Frames</a></li> |
| <li><a href="Connection.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> |
