This page is kept for archive. Please visit the GroovyJMS doc page for the latest documentation.


Let's start with some examples first:

Setup JMS Connection Factory

  1. Download the and extract the groovy.jms.JMS.groovy to your project
  2. For every example, it's assumed a JMS Connection Factory called "jms" is existed. For example, you could create a ActiveMQ connection factory programmatically with:
ConnectionFactory jms = new ActiveMQConnectionFactory(brokerURL: "vm://localhost");

Simple usages

  1. Subscribe to a Topic message
     jms.topic("greeting").subscribe({Message m \-> println "hey i got a message. it says, '${m.text}'"} as MessageListener);
     jms.close(); //optional
  2. Send a message to a Queue or Topic
    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
  3. Receive a Queue message
     Message message = jms.queue("greeting").receive(1000); // it does \*not\* mean get 1,000 message, see the note below this box
     List<Message> messages = jms.queue("greeting").receiveAll(1000); // this retrieve all messages within the 1000ms timeout interval
     jms.close(); //optional
    The receive parameter means "receives the next message that arrives within the specified timeout interval", check JMS JavaDoc for details:
  4. Reply to a message
    // the first guy
     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
      // please do something here, otherwise the example does not make sense
      it.reply("hey, let me tell you secretly")
     jms.close(); //optional

Advanced Usages/Issues

  1. Connection and Session re-use
    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,
  2. When to close()?
  3. How to obtain reference to JMS resource and reuse?
  4. When you need to call start()?
    1. 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.
    2. 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.
    3. If you don't close your connection and keep reusing it, you may probably need to call start() at some points.
  5. Exception Handling
    1. it creates a exception listener that log to a log4j logger
      conn.setExceptionListener({JMSException e \-> logger.error("JMS Exception", e)} as ExceptionListener);
    2. 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)
  6. 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.

Dependency, Limitations, and TODO

And you'll need the following jars:

For ActiveMQ core:
 activemq-all-*.jar // tested with activemq-all-5.3-SNAPSHOT.jar only

For Spring AMQ prefix:
 activeio-core.jar (it's not needed if you don't use the io persitence)