Copy Page

You are not logged in. Any changes you make will be marked as anonymous. You may want to Log In if you already have an account. You can also Sign Up for a new account.

<p>This page is kept for archive. Please visit the <a class="confluence-link" href="/display/GROOVY/GroovyJMS+Docs" data-linked-resource-id="108986375" data-linked-resource-type="page" data-linked-resource-default-alias="GroovyJMS Docs" data-base-url="http://docs.codehaus.org">GroovyJMS doc page</a> for the latest documentation.</p>

<h1>Examples</h1>

<p>Let's start with some examples first:</p>

<h3>Setup JMS Connection Factory</h3>

<ol>
	<li>Download the <a class="confluence-link unresolved" data-filename="GroovyJMS-v0.1.zip" data-linked-resource-default-alias="GroovyJMS-v0.1.zip" href="#">GroovyJMS-v0.1.zip</a> and extract the groovy.jms.JMS.groovy to your project
	<ul>
		<li>remarks:
		<ul>
			<li>the current release is for review. it includes all necessary jar and Intellij IDEA profile for running the unit test. You basically only need one JMS.groovy file plus any depending jars, that may have existed in your project already.</li>
			<li>The attached zip bundle with <strong>ActiveMQ 5.3 snapshot compiled with JDK 6</strong>. You are highly recommended to try the new 0.2 snapshot by checking out from svn</li>
		</ul>
		</li>
	</ul>
	</li>
	<li>For every example, it's assumed a JMS Connection Factory called &quot;jms&quot; is existed. For example, you could create a ActiveMQ connection factory programmatically with:</li>
</ol>

<table class="wysiwyg-macro" data-macro-name="code" style="background-image: url(/plugins/servlet/confluence/placeholder/macro-heading?definition=e2NvZGV9&amp;locale=en_GB&amp;version=2); background-repeat: no-repeat;" data-macro-body-type="PLAIN_TEXT"><tr><td class="wysiwyg-macro-body"><pre>
ConnectionFactory jms = new ActiveMQConnectionFactory(brokerURL: "vm://localhost");
</pre></td></tr></table>
<p><br class="atl-forced-newline" /></p>

<h3>Simple usages</h3>

<ol>
	<li>Subscribe to a Topic message
<table class="wysiwyg-macro" data-macro-name="code" style="background-image: url(/plugins/servlet/confluence/placeholder/macro-heading?definition=e2NvZGV9&amp;locale=en_GB&amp;version=2); background-repeat: no-repeat;" data-macro-body-type="PLAIN_TEXT"><tr><td class="wysiwyg-macro-body"><pre>
use(JMS){
 jms.topic("greeting").subscribe({Message m \-> println "hey i got a message. it says, '${m.text}'"} as MessageListener);
 jms.close(); //optional
}
</pre></td></tr></table></li>
	<li>Send a message to a Queue or Topic
<table class="wysiwyg-macro" data-macro-name="code" style="background-image: url(/plugins/servlet/confluence/placeholder/macro-heading?definition=e2NvZGV9&amp;locale=en_GB&amp;version=2); background-repeat: no-repeat;" data-macro-body-type="PLAIN_TEXT"><tr><td class="wysiwyg-macro-body"><pre>
use(JMS) {
 jms.topic("greeting").send("I'm joining the JMS party"); // use jms.queue("greeting queue") for sending to a queue
 jms.close(); //optional
}
</pre></td></tr></table></li>
	<li>Receive a Queue message
<table class="wysiwyg-macro" data-macro-name="code" style="background-image: url(/plugins/servlet/confluence/placeholder/macro-heading?definition=e2NvZGV9&amp;locale=en_GB&amp;version=2); background-repeat: no-repeat;" data-macro-body-type="PLAIN_TEXT"><tr><td class="wysiwyg-macro-body"><pre>
use(JMS){
 Message message = jms.queue("greeting").receive(1000); // it does \*not\* mean get 1,000 message, see the note below this box
 List&lt;Message> messages = jms.queue("greeting").receiveAll(1000); // this retrieve all messages within the 1000ms timeout interval
 jms.close(); //optional
}
</pre></td></tr></table>
The receive parameter means &quot;receives the next message that arrives within the specified timeout interval&quot;, check JMS JavaDoc for details:<br />
<a href="http://java.sun.com/javaee/5/docs/api/javax/jms/MessageConsumer.html#receive(long)">http://java.sun.com/javaee/5/docs/api/javax/jms/MessageConsumer.html</a></li>
	<li>Reply to a message
<table class="wysiwyg-macro" data-macro-name="code" style="background-image: url(/plugins/servlet/confluence/placeholder/macro-heading?definition=e2NvZGV9&amp;locale=en_GB&amp;version=2); background-repeat: no-repeat;" data-macro-body-type="PLAIN_TEXT"><tr><td class="wysiwyg-macro-body"><pre>
// the first guy
use(JMS){
 Queue replyQueue = jms.session().createQueue("replyQueue"); // notice that createQueue is the original JMS API, it's just an example, u could use jms.queue("replyQueue")
 jms.queue("greeting").send("hey, please reply to me privately", [JMSCorrelationID: 'privatePlease', JMSReplyTo: replyQueue])
 jms.close(); //optional
}

// another guy in another thread
use(JMS){
 jms.queue("greeting").receive(1000)?.with{
  // please do something here, otherwise the example does not make sense
  it.reply("hey, let me tell you secretly")
  };
 jms.close(); //optional
}
</pre></td></tr></table></li>
</ol>

<h3>Advanced Usages/Issues</h3>

<ol>
	<li>Connection and Session re-use<br />
By default, it reuses a single JMS Connection and Session. The connection and session are created when any of connect(), session(), topic() or queue() method is first called, and the connection and session are binded to internal ThreadLocal variables until close() is called. So,
	<ul>
		<li>connection and session are not shared across threads, it's thread-safe</li>
		<li>you have to call close() to remove a session in order to use a new connection and session.</li>
	</ul>
	</li>
	<li>When to close()?
	<ul>
		<li>The close() method call a connection.start(), unset all ThreadLocal variables, and call the connection.close() to close the connection.</li>
		<li>For server applications, every request are run in its own thread, and the thread may be re-used. It's recommended to close() a connection explicitly. Notice that it may not necessarily a problem to re-use a thread scope session.</li>
	</ul>
	</li>
	<li>How to obtain reference to JMS resource and reuse?
	<ul>
		<li>For singleton services in server applications, notice that the GroovyJMS is thread safe in a way different thread has its own connection and session. If you want to share the Connection and/or Session, simply create the connection and session. If you want to utilize the convenient connect() and session() methods, you could use:
<table class="wysiwyg-macro" data-macro-name="code" style="background-image: url(/plugins/servlet/confluence/placeholder/macro-heading?definition=e2NvZGV9&amp;locale=en_GB&amp;version=2); background-repeat: no-repeat;" data-macro-body-type="PLAIN_TEXT"><tr><td class="wysiwyg-macro-body"><pre>
def Connection jmsConnection;
use(JMS){
 jmsConnection = jms.connect();
 jms.cleanupThreadLocalVariables(); //clear all ThreadLocal variables
}
</pre></td></tr></table></li>
		<li>It's a matter of taste. You for sure can call the origianl jms.createConnection() directly. But if you will do some jms operation, it will save some code. You could also retrieve any created Connection and Session with:
<table class="wysiwyg-macro" data-macro-name="code" style="background-image: url(/plugins/servlet/confluence/placeholder/macro-heading?definition=e2NvZGV9&amp;locale=en_GB&amp;version=2); background-repeat: no-repeat;" data-macro-body-type="PLAIN_TEXT"><tr><td class="wysiwyg-macro-body"><pre>
//no need the "use(JMS)" for this case
Connection connectioin = JMS.connection.get();
Session session = JMS.session.get();
</pre></td></tr></table></li>
		<li>Because dynamic method are added to different JMS objects, the following are essentially the same:
<table class="wysiwyg-macro" data-macro-name="code" style="background-image: url(/plugins/servlet/confluence/placeholder/macro-heading?definition=e2NvZGV9&amp;locale=en_GB&amp;version=2); background-repeat: no-repeat;" data-macro-body-type="PLAIN_TEXT"><tr><td class="wysiwyg-macro-body"><pre>
jms.queue("myQueue")
 jms.connect().queue("myQueue")
 Connection conn = jms.connect(); conn.queue("myQueue")
 jms.session().queue("myQueue")
// but no jms.connect().session().queue("myQueue"); it's too much\! Please use the JMS createSession() api
</pre></td></tr></table></li>
	</ul>
	</li>
	<li>When you need to call start()?
	<ol>
		<li>If you have stopped a connection, you have to start it. otherwise, you won't get any message. Refer to the JMS specification. The only difference of GroovyJMS is that you could call start() directly on a ConnectionFactory.</li>
		<li>When a connection is first obtained, the start() method is called. You need to explicitly stop it if you don't want to receive message.</li>
		<li>If you don't close your connection and keep reusing it, you may probably need to call start() at some points.</li>
	</ol>
	</li>
	<li>Exception Handling
	<ol>
		<li>it creates a exception listener that log to a log4j logger
<table class="wysiwyg-macro" data-macro-name="code" style="background-image: url(/plugins/servlet/confluence/placeholder/macro-heading?definition=e2NvZGV9&amp;locale=en_GB&amp;version=2); background-repeat: no-repeat;" data-macro-body-type="PLAIN_TEXT"><tr><td class="wysiwyg-macro-body"><pre>
conn.setExceptionListener({JMSException e \-> logger.error("JMS Exception", e)} as ExceptionListener);
</pre></td></tr></table></li>
		<li>For some operations, it may throw RuntimeException. e.g. if you call reply on a message that does not have a reply address. It may be better to throw JMSException. (looking for your comment, notice that JMSException is not RuntimeException)</li>
	</ol>
	</li>
	<li>Notice that GroovyJMS simply add methods to the default JMS API. You could do whatever you like directly with JMS API. The JMS.groovy has under 250 line of code (incl. min comments) that it should not difficult to understand.</li>
</ol>

<h3>Dependency, Limitations, and TODO</h3>

<ul>
	<li>
	<ul>
		<li>You can only send TextMessage or manually create a JMS Message for now! <img class="emoticon emoticon-smile" data-emoticon-name="smile" border="0" src="/s/en_GB/3278/15/_/images/icons/emoticons/smile.png" alt="(smile)" title="(smile)" /> If anyone needs, i could add the convenient method to send other types of JMS message such as Map Message.</li>
		<li>It obviously require JMS api and a JMS implementation. You have to provide the JMS Factory, the following is an example to setup ActiveMQ with Spring:
<table class="wysiwyg-macro" data-macro-name="code" data-macro-default-parameter="xml" style="background-image: url(/plugins/servlet/confluence/placeholder/macro-heading?definition=e2NvZGU6eG1sfQ&amp;locale=en_GB&amp;version=2); background-repeat: no-repeat;" data-macro-body-type="PLAIN_TEXT"><tr><td class="wysiwyg-macro-body"><pre>
&lt;?xml version="1.0" encoding="UTF-8"?>

&lt;beans xmlns="http://www.springframework.org/schema/beans"
       xmlns:amq="http://activemq.apache.org/schema/core"
       xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
       xsi:schemaLocation="http://www.springframework.org/schema/beans http://www.springframework.org/schema/beans/spring-beans-2.5.xsd
						http://activemq.apache.org/schema/core http://activemq.apache.org/schema/core/activemq-core-5.1.0.xsd">

&lt;amq:broker useJmx="false" persistent="false">
        &lt;amq:transportConnectors>
            &lt;amq:transportConnector uri="vm://localhost"/>
        &lt;/amq:transportConnectors>
    &lt;/amq:broker>
    &lt;amq:connectionFactory id="connectionFactory" brokerURL="vm://localhost"/>
</pre></td></tr></table></li>
	</ul>
	</li>
</ul>

<p>And you'll need the following jars:</p>
<table class="wysiwyg-macro" data-macro-name="code" style="background-image: url(/plugins/servlet/confluence/placeholder/macro-heading?definition=e2NvZGV9&amp;locale=en_GB&amp;version=2); background-repeat: no-repeat;" data-macro-body-type="PLAIN_TEXT"><tr><td class="wysiwyg-macro-body"><pre>
For ActiveMQ core:
 activemq-all-*.jar // tested with activemq-all-5.3-SNAPSHOT.jar only

For Spring AMQ prefix:
 xbean-spring-2.6
 activeio-core.jar (it's not needed if you don't use the io persitence)
</pre></td></tr></table>