It's a Groovy Categories that make it very easy to use JMS in Groovy application. It adds some thread-safe convenient methods to the JMS APIs.
Let's start with some examples first:
Setup JMS Connection Factory
- Download the GroovyJMS-v0.1.zip (notice: it's an initial version for preview, see the limitation section), there are two files only, put the JMS.groovy in your project folder.
- 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:
- Subscribe to a Topic message
- Send a message to a Queue or Topic
- Receive a Queue message
The receive parameter means "receives the next message that arrives within the specified timeout interval", check JMS JavaDoc for details:
- Reply to a message
- 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 share/re-used across threads
- you have to call close() to remove a session in order to use a new connection and session.
- 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.
- 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:
- 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:
- Because dynamic method are added to different JMS objects, the following are essentially the same:
- When you need to call start()?
- 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.
- 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.
- If you don't close your connection and keep reusing it, you may probably need to call start() at some points.
- Exception Handling
- it creates a exception listener that log to a log4j logger
- 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)
- 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:
And you'll need the following jars:
- It's current hardcoded to use Log4j. It could be changed or removed on request.
- I've a line to set the Thread ID to a MDC "tid" variable. You may remove it if you don't like.
- TODO: change to a Groovish package name