activemq-artemis/examples/jms/last-value-queue/readme.html

142 lines
7.2 KiB
HTML

<html>
<head>
<title>ActiveMQ Last-Value Queue Example</title>
<link rel="stylesheet" type="text/css" href="../common/common.css" />
<link rel="stylesheet" type="text/css" href="../common/prettify.css" />
<script type="text/javascript" src="../common/prettify.js"></script>
</head>
<body onload="prettyPrint()">
<h1>Last-Value Queue Example</h1>
<p>This example shows you how to configure and use last-value queues.</p>
<p>Last-Value queues are special queues which discard any messages when a newer message with the same value for a well-defined <em>Last-Value</em> property is put in the queue.
In other words, a Last-Value queue only retains the last value.</p>
<p>A typical example for Last-Value queue is for stock prices, where you are only interested by the latest value for a particular stock.</p>
<p>The example will send 3 messages with the same <em>Last-Value</em> property to a to a Last-Value queue.<br />
We will browse the queue and see that only the last message is in the queue, the first two messages have been discarded. <br />
We will then consume from the queue the <em>last</em> message.</p>
<h2>Example setup</h2>
<p>Last-Value queues are defined in the configuration file <a href="server0/hornetq-configuration.xml">hornetq-configuration.xml</a>:</p>
<pre class="prettyprint">
<code>&lt;address-setting match="jms.queue.lastValueQueue"&gt;
&lt;last-value-queue&gt;true&lt;/last-value-queue&gt;
&lt;/address-setting&gt;</code>
</pre>
<h2>Example step-by-step</h2>
<p><i>To run the example, simply type <code>mvn verify</code> from this directory</i></p>
<ol>
<li>First we need to get an initial context so we can look-up the JMS connection factory and destination objects from JNDI. This initial context will get it's properties from the <a href="server0/client-jndi.properties">client-jndi.properties</a></li>
<pre class="prettyprint">
<code>InitialContext initialContext = getContext();</code>
</pre>
<li>We look up the JMS queue object from JNDI</li>
<pre class="prettyprint">
<code>Queue queue = (Queue) initialContext.lookup("/queue/lastValueQueue");</code>
</pre>
<li>We look up the JMS connection factory object from JNDI</li>
<pre class="prettyprint">
<code>ConnectionFactory cf = (ConnectionFactory) initialContext.lookup("/ConnectionFactory");</code>
</pre>
<li>We create a JMS connection, a session and a producer for the queue</li>
<pre class="prettyprint">
<code> connection = cf.createConnection();
Session session = connection.createSession(false, Session.AUTO_ACKNOWLEDGE);
MessageProducer producer = session.createProducer(queue);</code>
</pre>
<li>We will create and send a text message with the Last-Value property set to <code>STOCK_NAME</code></li>
<pre class="prettyprint">
<code>TextMessage message = session.createTextMessage("1st message with Last-Value property set");
message.setStringProperty("_HQ_LVQ_NAME", "STOCK_NAME");
producer.send(message);
System.out.format("Sent message: %s\n", message.getText());</code>
</pre>
<p><em>The <em>Last-Value</em> key is defined in ActiveMQ's MessageImpl class. Its value is <code>"_HQ_LVQ_NAME"</code></em></p>
<li>We will create and send a <em>second</em> text message with the Last-Value property set to <code>STOCK_NAME</code></li>
<pre class="prettyprint">
<code>message = session.createTextMessage("2nd message with Last-Value property set");
message.setStringProperty("_HQ_LVQ_NAME", "STOCK_NAME");
producer.send(message);
System.out.format("Sent message: %s\n", message.getText());</code>
</pre>
<li>We will create and send a <em>third</em> text message with the Last-Value property set to <code>STOCK_NAME</code></li>
<pre class="prettyprint">
<code>message = session.createTextMessage("3rd message with Last-Value property set");
message.setStringProperty("_HQ_LVQ_NAME", "STOCK_NAME");
producer.send(message);
System.out.format("Sent message: %s\n", message.getText());</code>
</pre>
<p><em>When the 2<sup>nd</sup> message was sent to the queue, the 1<sup>st</sup> message was discarded.<br />
Similarly, when the 3<sup>rd</sup> message was sent to the queue, the 2<sup>nd</sup> message was discarded.<br />
Only the 3<sup>rd</sup> message remains in the queue.</em></p>
<li>We will browse the queue. There will be a single message displayed: the 3<sup>rd</sup> message</li>
<pre class="prettyprint">
<code>QueueBrowser browser = session.createBrowser(queue);
Enumeration enumeration = browser.getEnumeration();
while (enumeration.hasMoreElements())
{
TextMessage messageInTheQueue = (TextMessage)enumeration.nextElement();
System.out.format("Message in the queue: %s\n", messageInTheQueue.getText());
}
browser.close();
</code>
</pre>
<p><em>We will now consume the message on the queue</em></p>
<li>We create a JMS message consumer on the queue</li>
<pre class="prettyprint">
<code>MessageConsumer messageConsumer = session.createConsumer(queue);</code>
</pre>
<li>We start the connection. In order for delivery to occur on any consumers or subscribers on a connection, the connection must be started</li>
<pre class="prettyprint">
<code>connection.start();</code>
</pre>
<li>We try to receive a message from the queue. It will be the 3<sup>rd</sup> message</li>
<pre class="prettyprint">
<code> TextMessage messageReceived = (TextMessage)messageConsumer.receive(5000);
System.out.format("Received message: %s\n", messageReceived.getText());</code>
</pre>
<li>We will try to receive another message but there is no other on the queue. The <code>receive</code> method will timeout after 5 seconds</li>
<pre class="prettyprint">
<code> messageReceived = (TextMessage)messageConsumer.receive(5000);
System.out.format("Received message: %s\n", messageReceived);</code>
</pre>
<li>And finally, <b>always</b> remember to close your JMS connections and resources after use, in a <code>finally</code> block. Closing a JMS connection will automatically close all of its sessions, consumers, producer and browser objects</li>
<pre class="prettyprint">
<code>finally
{
if (initialContext != null)
{
initialContext.close();
}
if (connection != null)
{
connection.close();
}
}</code>
</pre>
</ol>
<h2>More information</h2>
<ul>
<li>User Manual's <a href="../../../docs/user-manual/en/html_single/index.html#last-value-queues">Last-Value Queues chapter</a></li>
</ul>
</body>
</html>