jakartaee-9.0/javadoc/jakarta/jms/MessageConsumer.html - tomee-site-pub - Git at Google

 <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
 <!-- NewPage -->
 <html lang="en">
 <head>
 <title>MessageConsumer</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="MessageConsumer";
         }
     }
     catch(err) {
     }
 //-->
 var methods = {"i0":6,"i1":6,"i2":6,"i3":6,"i4":6,"i5":6,"i6":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="../../jakarta/jms/Message.html" title="interface in jakarta.jms"><span class="typeNameLink">Prev&nbsp;Class</span></a></li>
 <li><a href="../../jakarta/jms/MessageEOFException.html" title="class in jakarta.jms"><span class="typeNameLink">Next&nbsp;Class</span></a></li>
 </ul>
 <ul class="navList">
 <li><a href="../../index.html?jakarta/jms/MessageConsumer.html" target="_top">Frames</a></li>
 <li><a href="MessageConsumer.html" target="_top">No&nbsp;Frames</a></li>
 </ul>
 <ul class="navList" id="allclasses_navbar_top">
 <li><a href="../../allclasses-noframe.html">All&nbsp;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:&nbsp;</li>
 <li>Nested&nbsp;|&nbsp;</li>
 <li>Field&nbsp;|&nbsp;</li>
 <li>Constr&nbsp;|&nbsp;</li>
 <li><a href="#method.summary">Method</a></li>
 </ul>
 <ul class="subNavList">
 <li>Detail:&nbsp;</li>
 <li>Field&nbsp;|&nbsp;</li>
 <li>Constr&nbsp;|&nbsp;</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">jakarta.jms</div>
 <h2 title="Interface MessageConsumer" class="title">Interface MessageConsumer</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="../../jakarta/jms/QueueReceiver.html" title="interface in jakarta.jms">QueueReceiver</a>, <a href="../../jakarta/jms/TopicSubscriber.html" title="interface in jakarta.jms">TopicSubscriber</a></dd>
 </dl>
 <hr>
 <br>
 <pre>public interface <span class="typeNameLabel">MessageConsumer</span>
 extends java.lang.AutoCloseable</pre>
 <div class="block">A client uses a <code>MessageConsumer</code> object to receive messages from a destination. A <code>MessageConsumer</code>
  object is created by passing a <code>Destination</code> object to a message-consumer creation method supplied by a
  session.

  <p>
  <code>MessageConsumer</code> is the parent interface for all message consumers.

  <p>
  A <code>MessageConsumer</code> can be created with a message selector. A message selector allows the client to restrict
  the messages delivered to the message consumer to those that match the selector.

  <p>
  A client may either synchronously receive a <code>MessageConsumer</code>'s messages or have the <code>MessageConsumer</code>
  asynchronously deliver them as they arrive.

  <p>
  For synchronous receipt, a client can request the next message from a <code>MessageConsumer</code> using one of its
  <code>receive</code> methods. There are several variations of <code>receive</code> that allow a client to poll or wait for the
  next message.

  <p>
  For asynchronous delivery, a client can register a <code>MessageListener</code> object with a <code>MessageConsumer</code>. As
  messages arrive at the <code>MessageConsumer</code>, it delivers them by calling the <code>MessageListener</code>'s
  <code>onMessage</code> method.

  <p>
  It is a client programming error for a <code>MessageListener</code> to throw an exception.</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="../../jakarta/jms/QueueReceiver.html" title="interface in jakarta.jms"><code>QueueReceiver</code></a>,
 <a href="../../jakarta/jms/TopicSubscriber.html" title="interface in jakarta.jms"><code>TopicSubscriber</code></a>,
 <a href="../../jakarta/jms/Session.html" title="interface in jakarta.jms"><code>Session</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">&nbsp;</span></span><span id="t2" class="tableTab"><span><a href="javascript:show(2);">Instance Methods</a></span><span class="tabEnd">&nbsp;</span></span><span id="t3" class="tableTab"><span><a href="javascript:show(4);">Abstract Methods</a></span><span class="tabEnd">&nbsp;</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="../../jakarta/jms/MessageConsumer.html#close--">close</a></span>()</code>
 <div class="block">Closes the message consumer.</div>
 </td>
 </tr>
 <tr id="i1" class="rowColor">
 <td class="colFirst"><code><a href="../../jakarta/jms/MessageListener.html" title="interface in jakarta.jms">MessageListener</a></code></td>
 <td class="colLast"><code><span class="memberNameLink"><a href="../../jakarta/jms/MessageConsumer.html#getMessageListener--">getMessageListener</a></span>()</code>
 <div class="block">Gets the <code>MessageConsumer</code>'s <code>MessageListener</code>.</div>
 </td>
 </tr>
 <tr id="i2" class="altColor">
 <td class="colFirst"><code>java.lang.String</code></td>
 <td class="colLast"><code><span class="memberNameLink"><a href="../../jakarta/jms/MessageConsumer.html#getMessageSelector--">getMessageSelector</a></span>()</code>
 <div class="block">Gets this message consumer's message selector expression.</div>
 </td>
 </tr>
 <tr id="i3" class="rowColor">
 <td class="colFirst"><code><a href="../../jakarta/jms/Message.html" title="interface in jakarta.jms">Message</a></code></td>
 <td class="colLast"><code><span class="memberNameLink"><a href="../../jakarta/jms/MessageConsumer.html#receive--">receive</a></span>()</code>
 <div class="block">Receives the next message produced for this message consumer.</div>
 </td>
 </tr>
 <tr id="i4" class="altColor">
 <td class="colFirst"><code><a href="../../jakarta/jms/Message.html" title="interface in jakarta.jms">Message</a></code></td>
 <td class="colLast"><code><span class="memberNameLink"><a href="../../jakarta/jms/MessageConsumer.html#receive-long-">receive</a></span>(long&nbsp;timeout)</code>
 <div class="block">Receives the next message that arrives within the specified timeout interval.</div>
 </td>
 </tr>
 <tr id="i5" class="rowColor">
 <td class="colFirst"><code><a href="../../jakarta/jms/Message.html" title="interface in jakarta.jms">Message</a></code></td>
 <td class="colLast"><code><span class="memberNameLink"><a href="../../jakarta/jms/MessageConsumer.html#receiveNoWait--">receiveNoWait</a></span>()</code>
 <div class="block">Receives the next message if one is immediately available.</div>
 </td>
 </tr>
 <tr id="i6" class="altColor">
 <td class="colFirst"><code>void</code></td>
 <td class="colLast"><code><span class="memberNameLink"><a href="../../jakarta/jms/MessageConsumer.html#setMessageListener-jakarta.jms.MessageListener-">setMessageListener</a></span>(<a href="../../jakarta/jms/MessageListener.html" title="interface in jakarta.jms">MessageListener</a>&nbsp;listener)</code>
 <div class="block">Sets the <code>MessageConsumer</code>'s <code>MessageListener</code>.</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="getMessageSelector--">
 <!--   -->
 </a>
 <ul class="blockList">
 <li class="blockList">
 <h4>getMessageSelector</h4>
 <pre>java.lang.String&nbsp;getMessageSelector()
                              throws <a href="../../jakarta/jms/JMSException.html" title="class in jakarta.jms">JMSException</a></pre>
 <div class="block">Gets this message consumer's message selector expression.</div>
 <dl>
 <dt><span class="returnLabel">Returns:</span></dt>
 <dd>this message consumer's message selector, or null if no message selector exists for the message consumer
  (that is, if the message selector was not set or was set to null or the empty string)</dd>
 <dt><span class="throwsLabel">Throws:</span></dt>
 <dd><code><a href="../../jakarta/jms/JMSException.html" title="class in jakarta.jms">JMSException</a></code> - if the Jakarta Messaging provider fails to get the message selector due to some internal error.</dd>
 </dl>
 </li>
 </ul>
 <a name="getMessageListener--">
 <!--   -->
 </a>
 <ul class="blockList">
 <li class="blockList">
 <h4>getMessageListener</h4>
 <pre><a href="../../jakarta/jms/MessageListener.html" title="interface in jakarta.jms">MessageListener</a>&nbsp;getMessageListener()
                             throws <a href="../../jakarta/jms/JMSException.html" title="class in jakarta.jms">JMSException</a></pre>
 <div class="block">Gets the <code>MessageConsumer</code>'s <code>MessageListener</code>.

  <p>
  This method must not be used in a Jakarta 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="returnLabel">Returns:</span></dt>
 <dd>the <code>MessageConsumer</code>'s <code>MessageListener</code>, or null if one was not set</dd>
 <dt><span class="throwsLabel">Throws:</span></dt>
 <dd><code><a href="../../jakarta/jms/JMSException.html" title="class in jakarta.jms">JMSException</a></code> - if the Jakarta Messaging provider fails to get the <code>MessageListener</code> for one of the following
  reasons:
  <ul>
  <li>an internal error has occurred or
  <li>this method has been called in a Jakarta 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="../../jakarta/jms/MessageConsumer.html#setMessageListener-jakarta.jms.MessageListener-"><code>setMessageListener(jakarta.jms.MessageListener)</code></a></dd>
 </dl>
 </li>
 </ul>
 <a name="setMessageListener-jakarta.jms.MessageListener-">
 <!--   -->
 </a>
 <ul class="blockList">
 <li class="blockList">
 <h4>setMessageListener</h4>
 <pre>void&nbsp;setMessageListener(<a href="../../jakarta/jms/MessageListener.html" title="interface in jakarta.jms">MessageListener</a>&nbsp;listener)
                  throws <a href="../../jakarta/jms/JMSException.html" title="class in jakarta.jms">JMSException</a></pre>
 <div class="block">Sets the <code>MessageConsumer</code>'s <code>MessageListener</code>.

  <p>
  Setting the the <code>MessageListener</code> to null is the equivalent of unsetting the <code>MessageListener</code> for the
  <code>MessageConsumer</code>.

  <p>
  The effect of calling this method while messages are being consumed by an existing listener or the
  <code>MessageConsumer</code> is being used to consume messages synchronously is undefined.

  <p>
  This method must not be used in a Jakarta 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 listener to which the messages are to be delivered</dd>
 <dt><span class="throwsLabel">Throws:</span></dt>
 <dd><code><a href="../../jakarta/jms/JMSException.html" title="class in jakarta.jms">JMSException</a></code> - if the Jakarta Messaging provider fails to set the <code>MessageConsumer</code>'s <code>MessageListener</code> for
  one of the following reasons:
  <ul>
  <li>an internal error has occurred or
  <li>this method has been called in a Jakarta 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="../../jakarta/jms/MessageConsumer.html#getMessageListener--"><code>getMessageListener()</code></a></dd>
 </dl>
 </li>
 </ul>
 <a name="receive--">
 <!--   -->
 </a>
 <ul class="blockList">
 <li class="blockList">
 <h4>receive</h4>
 <pre><a href="../../jakarta/jms/Message.html" title="interface in jakarta.jms">Message</a>&nbsp;receive()
          throws <a href="../../jakarta/jms/JMSException.html" title="class in jakarta.jms">JMSException</a></pre>
 <div class="block">Receives the next message produced for this message consumer.

  <p>
  This call blocks indefinitely until a message is produced or until this message consumer is closed.

  <p>
  If this <code>receive</code> is done within a transaction, the consumer retains the message until the transaction commits.</div>
 <dl>
 <dt><span class="returnLabel">Returns:</span></dt>
 <dd>the next message produced for this message consumer, or null if this message consumer is concurrently closed</dd>
 <dt><span class="throwsLabel">Throws:</span></dt>
 <dd><code><a href="../../jakarta/jms/JMSException.html" title="class in jakarta.jms">JMSException</a></code> - if the Jakarta Messaging provider fails to receive the next message due to some internal error.</dd>
 </dl>
 </li>
 </ul>
 <a name="receive-long-">
 <!--   -->
 </a>
 <ul class="blockList">
 <li class="blockList">
 <h4>receive</h4>
 <pre><a href="../../jakarta/jms/Message.html" title="interface in jakarta.jms">Message</a>&nbsp;receive(long&nbsp;timeout)
          throws <a href="../../jakarta/jms/JMSException.html" title="class in jakarta.jms">JMSException</a></pre>
 <div class="block">Receives the next message that arrives within the specified timeout interval.

  <p>
  This call blocks until a message arrives, the timeout expires, or this message consumer is closed. A <code>timeout</code>
  of zero never expires, and the call blocks indefinitely.</div>
 <dl>
 <dt><span class="paramLabel">Parameters:</span></dt>
 <dd><code>timeout</code> - the timeout value (in milliseconds)</dd>
 <dt><span class="returnLabel">Returns:</span></dt>
 <dd>the next message produced for this message consumer, or null if the timeout expires or this message consumer
  is concurrently closed</dd>
 <dt><span class="throwsLabel">Throws:</span></dt>
 <dd><code><a href="../../jakarta/jms/JMSException.html" title="class in jakarta.jms">JMSException</a></code> - if the Jakarta Messaging provider fails to receive the next message due to some internal error.</dd>
 </dl>
 </li>
 </ul>
 <a name="receiveNoWait--">
 <!--   -->
 </a>
 <ul class="blockList">
 <li class="blockList">
 <h4>receiveNoWait</h4>
 <pre><a href="../../jakarta/jms/Message.html" title="interface in jakarta.jms">Message</a>&nbsp;receiveNoWait()
                throws <a href="../../jakarta/jms/JMSException.html" title="class in jakarta.jms">JMSException</a></pre>
 <div class="block">Receives the next message if one is immediately available.</div>
 <dl>
 <dt><span class="returnLabel">Returns:</span></dt>
 <dd>the next message produced for this message consumer, or null if one is not available</dd>
 <dt><span class="throwsLabel">Throws:</span></dt>
 <dd><code><a href="../../jakarta/jms/JMSException.html" title="class in jakarta.jms">JMSException</a></code> - if the Jakarta Messaging provider fails to receive the next message due to some internal error.</dd>
 </dl>
 </li>
 </ul>
 <a name="close--">
 <!--   -->
 </a>
 <ul class="blockListLast">
 <li class="blockList">
 <h4>close</h4>
 <pre>void&nbsp;close()
     throws <a href="../../jakarta/jms/JMSException.html" title="class in jakarta.jms">JMSException</a></pre>
 <div class="block">Closes the message consumer.

  <p>
  Since a provider may allocate some resources on behalf of a <code>MessageConsumer</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 call will block until a <code>receive</code> call in progress on this consumer has completed. A blocked
  <code>receive</code> call returns null when this message consumer is closed.

  <p>
  If this method is called whilst a message listener is in progress in another thread then it will block until the
  message listener has completed.

  <p>
  This method may be called from a message listener's <code>onMessage</code> method on its own consumer. After this method
  returns the <code>onMessage</code> method will be allowed to complete normally.

  <p>
  This method is the only <code>MessageConsumer</code> method that can be called concurrently.</div>
 <dl>
 <dt><span class="overrideSpecifyLabel">Specified by:</span></dt>
 <dd><code>close</code>&nbsp;in interface&nbsp;<code>java.lang.AutoCloseable</code></dd>
 <dt><span class="throwsLabel">Throws:</span></dt>
 <dd><code><a href="../../jakarta/jms/JMSException.html" title="class in jakarta.jms">JMSException</a></code> - if the Jakarta Messaging provider fails to close the consumer due to some internal error.</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="../../jakarta/jms/Message.html" title="interface in jakarta.jms"><span class="typeNameLink">Prev&nbsp;Class</span></a></li>
 <li><a href="../../jakarta/jms/MessageEOFException.html" title="class in jakarta.jms"><span class="typeNameLink">Next&nbsp;Class</span></a></li>
 </ul>
 <ul class="navList">
 <li><a href="../../index.html?jakarta/jms/MessageConsumer.html" target="_top">Frames</a></li>
 <li><a href="MessageConsumer.html" target="_top">No&nbsp;Frames</a></li>
 </ul>
 <ul class="navList" id="allclasses_navbar_bottom">
 <li><a href="../../allclasses-noframe.html">All&nbsp;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:&nbsp;</li>
 <li>Nested&nbsp;|&nbsp;</li>
 <li>Field&nbsp;|&nbsp;</li>
 <li>Constr&nbsp;|&nbsp;</li>
 <li><a href="#method.summary">Method</a></li>
 </ul>
 <ul class="subNavList">
 <li>Detail:&nbsp;</li>
 <li>Field&nbsp;|&nbsp;</li>
 <li>Constr&nbsp;|&nbsp;</li>
 <li><a href="#method.detail">Method</a></li>
 </ul>
 </div>
 <a name="skip.navbar.bottom">
 <!--   -->
 </a></div>
 <!-- ======== END OF BOTTOM NAVBAR ======= -->
 </body>
 </html>
	<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
	<!-- NewPage -->
	<html lang="en">
	<head>
	<title>MessageConsumer</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="MessageConsumer";
	}
	}
	catch(err) {
	}
	//-->
	var methods = {"i0":6,"i1":6,"i2":6,"i3":6,"i4":6,"i5":6,"i6":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="../../jakarta/jms/Message.html" title="interface in jakarta.jms"><span class="typeNameLink">Prev Class</span></a></li>
	<li><a href="../../jakarta/jms/MessageEOFException.html" title="class in jakarta.jms"><span class="typeNameLink">Next Class</span></a></li>
	</ul>
	<ul class="navList">
	<li><a href="../../index.html?jakarta/jms/MessageConsumer.html" target="_top">Frames</a></li>
	<li><a href="MessageConsumer.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">jakarta.jms</div>
	<h2 title="Interface MessageConsumer" class="title">Interface MessageConsumer</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="../../jakarta/jms/QueueReceiver.html" title="interface in jakarta.jms">QueueReceiver</a>, <a href="../../jakarta/jms/TopicSubscriber.html" title="interface in jakarta.jms">TopicSubscriber</a></dd>
	</dl>
	<hr>
	<br>
	<pre>public interface <span class="typeNameLabel">MessageConsumer</span>
	extends java.lang.AutoCloseable</pre>
	<div class="block">A client uses a <code>MessageConsumer</code> object to receive messages from a destination. A <code>MessageConsumer</code>
	object is created by passing a <code>Destination</code> object to a message-consumer creation method supplied by a
	session.

	<p>
	<code>MessageConsumer</code> is the parent interface for all message consumers.

	<p>
	A <code>MessageConsumer</code> can be created with a message selector. A message selector allows the client to restrict
	the messages delivered to the message consumer to those that match the selector.

	<p>
	A client may either synchronously receive a <code>MessageConsumer</code>'s messages or have the <code>MessageConsumer</code>
	asynchronously deliver them as they arrive.

	<p>
	For synchronous receipt, a client can request the next message from a <code>MessageConsumer</code> using one of its
	<code>receive</code> methods. There are several variations of <code>receive</code> that allow a client to poll or wait for the
	next message.

	<p>
	For asynchronous delivery, a client can register a <code>MessageListener</code> object with a <code>MessageConsumer</code>. As
	messages arrive at the <code>MessageConsumer</code>, it delivers them by calling the <code>MessageListener</code>'s
	<code>onMessage</code> method.

	<p>
	It is a client programming error for a <code>MessageListener</code> to throw an exception.</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="../../jakarta/jms/QueueReceiver.html" title="interface in jakarta.jms"><code>QueueReceiver</code></a>,
	<a href="../../jakarta/jms/TopicSubscriber.html" title="interface in jakarta.jms"><code>TopicSubscriber</code></a>,
	<a href="../../jakarta/jms/Session.html" title="interface in jakarta.jms"><code>Session</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="../../jakarta/jms/MessageConsumer.html#close--">close</a></span>()</code>
	<div class="block">Closes the message consumer.</div>
	</td>
	</tr>
	<tr id="i1" class="rowColor">
	<td class="colFirst"><code><a href="../../jakarta/jms/MessageListener.html" title="interface in jakarta.jms">MessageListener</a></code></td>
	<td class="colLast"><code><span class="memberNameLink"><a href="../../jakarta/jms/MessageConsumer.html#getMessageListener--">getMessageListener</a></span>()</code>
	<div class="block">Gets the <code>MessageConsumer</code>'s <code>MessageListener</code>.</div>
	</td>
	</tr>
	<tr id="i2" class="altColor">
	<td class="colFirst"><code>java.lang.String</code></td>
	<td class="colLast"><code><span class="memberNameLink"><a href="../../jakarta/jms/MessageConsumer.html#getMessageSelector--">getMessageSelector</a></span>()</code>
	<div class="block">Gets this message consumer's message selector expression.</div>
	</td>
	</tr>
	<tr id="i3" class="rowColor">
	<td class="colFirst"><code><a href="../../jakarta/jms/Message.html" title="interface in jakarta.jms">Message</a></code></td>
	<td class="colLast"><code><span class="memberNameLink"><a href="../../jakarta/jms/MessageConsumer.html#receive--">receive</a></span>()</code>
	<div class="block">Receives the next message produced for this message consumer.</div>
	</td>
	</tr>
	<tr id="i4" class="altColor">
	<td class="colFirst"><code><a href="../../jakarta/jms/Message.html" title="interface in jakarta.jms">Message</a></code></td>
	<td class="colLast"><code><span class="memberNameLink"><a href="../../jakarta/jms/MessageConsumer.html#receive-long-">receive</a></span>(long timeout)</code>
	<div class="block">Receives the next message that arrives within the specified timeout interval.</div>
	</td>
	</tr>
	<tr id="i5" class="rowColor">
	<td class="colFirst"><code><a href="../../jakarta/jms/Message.html" title="interface in jakarta.jms">Message</a></code></td>
	<td class="colLast"><code><span class="memberNameLink"><a href="../../jakarta/jms/MessageConsumer.html#receiveNoWait--">receiveNoWait</a></span>()</code>
	<div class="block">Receives the next message if one is immediately available.</div>
	</td>
	</tr>
	<tr id="i6" class="altColor">
	<td class="colFirst"><code>void</code></td>
	<td class="colLast"><code><span class="memberNameLink"><a href="../../jakarta/jms/MessageConsumer.html#setMessageListener-jakarta.jms.MessageListener-">setMessageListener</a></span>(<a href="../../jakarta/jms/MessageListener.html" title="interface in jakarta.jms">MessageListener</a> listener)</code>
	<div class="block">Sets the <code>MessageConsumer</code>'s <code>MessageListener</code>.</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="getMessageSelector--">
	<!-- -->
	</a>
	<ul class="blockList">
	<li class="blockList">
	<h4>getMessageSelector</h4>
	<pre>java.lang.String getMessageSelector()
	throws <a href="../../jakarta/jms/JMSException.html" title="class in jakarta.jms">JMSException</a></pre>
	<div class="block">Gets this message consumer's message selector expression.</div>
	<dl>
	<dt><span class="returnLabel">Returns:</span></dt>
	<dd>this message consumer's message selector, or null if no message selector exists for the message consumer
	(that is, if the message selector was not set or was set to null or the empty string)</dd>
	<dt><span class="throwsLabel">Throws:</span></dt>
	<dd><code><a href="../../jakarta/jms/JMSException.html" title="class in jakarta.jms">JMSException</a></code> - if the Jakarta Messaging provider fails to get the message selector due to some internal error.</dd>
	</dl>
	</li>
	</ul>
	<a name="getMessageListener--">
	<!-- -->
	</a>
	<ul class="blockList">
	<li class="blockList">
	<h4>getMessageListener</h4>
	<pre><a href="../../jakarta/jms/MessageListener.html" title="interface in jakarta.jms">MessageListener</a> getMessageListener()
	throws <a href="../../jakarta/jms/JMSException.html" title="class in jakarta.jms">JMSException</a></pre>
	<div class="block">Gets the <code>MessageConsumer</code>'s <code>MessageListener</code>.

	<p>
	This method must not be used in a Jakarta 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="returnLabel">Returns:</span></dt>
	<dd>the <code>MessageConsumer</code>'s <code>MessageListener</code>, or null if one was not set</dd>
	<dt><span class="throwsLabel">Throws:</span></dt>
	<dd><code><a href="../../jakarta/jms/JMSException.html" title="class in jakarta.jms">JMSException</a></code> - if the Jakarta Messaging provider fails to get the <code>MessageListener</code> for one of the following
	reasons:
	<ul>
	<li>an internal error has occurred or
	<li>this method has been called in a Jakarta 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="../../jakarta/jms/MessageConsumer.html#setMessageListener-jakarta.jms.MessageListener-"><code>setMessageListener(jakarta.jms.MessageListener)</code></a></dd>
	</dl>
	</li>
	</ul>
	<a name="setMessageListener-jakarta.jms.MessageListener-">
	<!-- -->
	</a>
	<ul class="blockList">
	<li class="blockList">
	<h4>setMessageListener</h4>
	<pre>void setMessageListener(<a href="../../jakarta/jms/MessageListener.html" title="interface in jakarta.jms">MessageListener</a> listener)
	throws <a href="../../jakarta/jms/JMSException.html" title="class in jakarta.jms">JMSException</a></pre>
	<div class="block">Sets the <code>MessageConsumer</code>'s <code>MessageListener</code>.

	<p>
	Setting the the <code>MessageListener</code> to null is the equivalent of unsetting the <code>MessageListener</code> for the
	<code>MessageConsumer</code>.

	<p>
	The effect of calling this method while messages are being consumed by an existing listener or the
	<code>MessageConsumer</code> is being used to consume messages synchronously is undefined.

	<p>
	This method must not be used in a Jakarta 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 listener to which the messages are to be delivered</dd>
	<dt><span class="throwsLabel">Throws:</span></dt>
	<dd><code><a href="../../jakarta/jms/JMSException.html" title="class in jakarta.jms">JMSException</a></code> - if the Jakarta Messaging provider fails to set the <code>MessageConsumer</code>'s <code>MessageListener</code> for
	one of the following reasons:
	<ul>
	<li>an internal error has occurred or
	<li>this method has been called in a Jakarta 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="../../jakarta/jms/MessageConsumer.html#getMessageListener--"><code>getMessageListener()</code></a></dd>
	</dl>
	</li>
	</ul>
	<a name="receive--">
	<!-- -->
	</a>
	<ul class="blockList">
	<li class="blockList">
	<h4>receive</h4>
	<pre><a href="../../jakarta/jms/Message.html" title="interface in jakarta.jms">Message</a> receive()
	throws <a href="../../jakarta/jms/JMSException.html" title="class in jakarta.jms">JMSException</a></pre>
	<div class="block">Receives the next message produced for this message consumer.

	<p>
	This call blocks indefinitely until a message is produced or until this message consumer is closed.

	<p>
	If this <code>receive</code> is done within a transaction, the consumer retains the message until the transaction commits.</div>
	<dl>
	<dt><span class="returnLabel">Returns:</span></dt>
	<dd>the next message produced for this message consumer, or null if this message consumer is concurrently closed</dd>
	<dt><span class="throwsLabel">Throws:</span></dt>
	<dd><code><a href="../../jakarta/jms/JMSException.html" title="class in jakarta.jms">JMSException</a></code> - if the Jakarta Messaging provider fails to receive the next message due to some internal error.</dd>
	</dl>
	</li>
	</ul>
	<a name="receive-long-">
	<!-- -->
	</a>
	<ul class="blockList">
	<li class="blockList">
	<h4>receive</h4>
	<pre><a href="../../jakarta/jms/Message.html" title="interface in jakarta.jms">Message</a> receive(long timeout)
	throws <a href="../../jakarta/jms/JMSException.html" title="class in jakarta.jms">JMSException</a></pre>
	<div class="block">Receives the next message that arrives within the specified timeout interval.

	<p>
	This call blocks until a message arrives, the timeout expires, or this message consumer is closed. A <code>timeout</code>
	of zero never expires, and the call blocks indefinitely.</div>
	<dl>
	<dt><span class="paramLabel">Parameters:</span></dt>
	<dd><code>timeout</code> - the timeout value (in milliseconds)</dd>
	<dt><span class="returnLabel">Returns:</span></dt>
	<dd>the next message produced for this message consumer, or null if the timeout expires or this message consumer
	is concurrently closed</dd>
	<dt><span class="throwsLabel">Throws:</span></dt>
	<dd><code><a href="../../jakarta/jms/JMSException.html" title="class in jakarta.jms">JMSException</a></code> - if the Jakarta Messaging provider fails to receive the next message due to some internal error.</dd>
	</dl>
	</li>
	</ul>
	<a name="receiveNoWait--">
	<!-- -->
	</a>
	<ul class="blockList">
	<li class="blockList">
	<h4>receiveNoWait</h4>
	<pre><a href="../../jakarta/jms/Message.html" title="interface in jakarta.jms">Message</a> receiveNoWait()
	throws <a href="../../jakarta/jms/JMSException.html" title="class in jakarta.jms">JMSException</a></pre>
	<div class="block">Receives the next message if one is immediately available.</div>
	<dl>
	<dt><span class="returnLabel">Returns:</span></dt>
	<dd>the next message produced for this message consumer, or null if one is not available</dd>
	<dt><span class="throwsLabel">Throws:</span></dt>
	<dd><code><a href="../../jakarta/jms/JMSException.html" title="class in jakarta.jms">JMSException</a></code> - if the Jakarta Messaging provider fails to receive the next message due to some internal error.</dd>
	</dl>
	</li>
	</ul>
	<a name="close--">
	<!-- -->
	</a>
	<ul class="blockListLast">
	<li class="blockList">
	<h4>close</h4>
	<pre>void close()
	throws <a href="../../jakarta/jms/JMSException.html" title="class in jakarta.jms">JMSException</a></pre>
	<div class="block">Closes the message consumer.

	<p>
	Since a provider may allocate some resources on behalf of a <code>MessageConsumer</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 call will block until a <code>receive</code> call in progress on this consumer has completed. A blocked
	<code>receive</code> call returns null when this message consumer is closed.

	<p>
	If this method is called whilst a message listener is in progress in another thread then it will block until the
	message listener has completed.

	<p>
	This method may be called from a message listener's <code>onMessage</code> method on its own consumer. After this method
	returns the <code>onMessage</code> method will be allowed to complete normally.

	<p>
	This method is the only <code>MessageConsumer</code> method that can be called concurrently.</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="../../jakarta/jms/JMSException.html" title="class in jakarta.jms">JMSException</a></code> - if the Jakarta Messaging provider fails to close the consumer due to some internal error.</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="../../jakarta/jms/Message.html" title="interface in jakarta.jms"><span class="typeNameLink">Prev Class</span></a></li>
	<li><a href="../../jakarta/jms/MessageEOFException.html" title="class in jakarta.jms"><span class="typeNameLink">Next Class</span></a></li>
	</ul>
	<ul class="navList">
	<li><a href="../../index.html?jakarta/jms/MessageConsumer.html" target="_top">Frames</a></li>
	<li><a href="MessageConsumer.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>