<!--
Licensed to the Apache Software Foundation (ASF) under one
or more contributor license agreements. See the NOTICE file
distributed with this work for additional information
regarding copyright ownership. The ASF licenses this file
to you under the Apache License, Version 2.0 (the
"License"); you may not use this file except in compliance
with the License. You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing,
software distributed under the License is distributed on an
"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
KIND, either express or implied. See the License for the
specific language governing permissions and limitations
under the License.
-->
<html>
<head>
<title>ActiveMQ Artemis 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/broker.xml">broker.xml</a>:</p>
<pre class="prettyprint">
<code><address-setting match="jms.queue.lastValueQueue">
<last-value-queue>true</last-value-queue>
</address-setting></code>
</pre>
<h2>Example step-by-step</h2>
<p><i>To run the example, simply type <code>mvn verify -Pexample</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("_AMQ_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>"_AMQ_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("_AMQ_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("_AMQ_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>
73c5f2e342