Examples

Let's start with some examples first:

Setup JMS Connection Factory

1. Download the GroovyJMS-v0.1.zip and extract the groovy.jms.JMS.groovy to your project
   • notice: 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.
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

   Code Block
   use(JMS){ 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

   Code Block
   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

   Code Block
   use(JMS){ 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:
   http://java.sun.com/javaee/5/docs/api/javax/jms/MessageConsumer.html
4. Reply to a message

   Code Block

   // 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 }

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,
   • connection and session are not shared across threads, it's thread-safe
   • you have to call close() to remove a session in order to use a new connection and session.
2. When to close()?
   • The close() method call a connection.start(), unset all ThreadLocal variables, and call the connection.close() to close the connection.
   • 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.
3. How to obtain reference to JMS resource and reuse?
   • 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:

     Code Block
     def Connection jmsConnection; use(JMS){ jmsConnection = jms.connect(); jms.cleanupThreadLocalVariables(); //clear all ThreadLocal variables }

   • 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:

     Code Block
     //no need the "use(JMS)" for this case Connection connectioin = JMS.connection.get(); Session session = JMS.session.get();

   • Because dynamic method are added to different JMS objects, the following are essentially the same:

     Code Block
     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

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

      Code Block
      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

• • You can only send TextMessage or manually create a JMS Message for now! If anyone needs, i could add the convenient method to send other types of JMS message such as Map Message.
  • 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:

    Code Block
    xml
    <?xml version="1.0" encoding="UTF-8"?> <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"> <amq:broker useJmx="false" persistent="false"> <amq:transportConnectors> <amq:transportConnector uri="vm://localhost"/> </amq:transportConnectors> </amq:broker> <amq:connectionFactory id="connectionFactory" brokerURL="vm://localhost"/>

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:
 xbean-spring-2.6
 activeio-core.jar (it's not needed if you don't use the io persitence)