This chapter shows how to use the Java Messaging Service (JMS) in JBoss. It is not meant to be a tutorial on JMS in general, but one on how to use JMS with JBoss. For introductions to JMS please read the JMS Specification or check out the JMS tutorial.

Lately, the JMS support in JBoss has gone through some rapid changes; as a result, there are some marked differences between the 2.2.x releases, the 2.4.x releases and the development version. This chapter is focused on the 2.2.x releases. Features only available in later releases will be marked by the corresponding revision number, either in the text or in a title. In an earlier version of this chapter the version number 2.5.x pointed to features only available in the development version of JBoss. Since then, with the release of JBossMQ 1.0beta, what was then said about 2.5.x is now valid for 2.4.1. References to 2.5.x have therefore been removed from this chapter. The examples covering 2.4.1 features, however, still contain “"25"” in their names. New features added to JBoss3.0 will be covered in a later version of this chapter.

Examples given in this chapter are short and to the point and they are here only to show how JMS may be used in principle. They are almost all of them based on the “Hello World” pattern. All the examples can be run through the provided example Ant build file.

Download the file and expand it someplace. Build and run the examples from the directory examples/build. All the source files for the JMS examples are available in the subdirectories below examples/org/jboss/docs/jms. In what follows, any mention of example source files should be understood to be relative to the examples directory.

To be able to build and run the JBoss documentation examples, the following environment variables need to be defined:

Table 6.1. Environment variables needed to run the examples

JAVA_HOMEThe location of a JDK 1.3, e.g. /opt/jdk1.3
JBOSS_DISTThe location of the JBoss installation, e.g. /opt/JBoss-2.2.2

The Ant bin directory and the JDK bin directory must also be in your PATH as described in the section called “Installing Ant” in the First Steps chapter of this manual.

As different examples work with different versions of JBoss, you will have to make sure that the JBOSS_DIST environment variable points to the correct version of JBoss for each particular example.

When this is done you may build the JMS examples like this:

Figure 6.1. Build JMS examples

cd examples/build
ant jms-compile

When cutting and pasting code examples it is always best to use the example source files and not the examples in the manual; the source files are checked both at compile time and at run time, but the text in the manual, although it should be the same, only goes through a visual inspection.

For some of the examples, under directory org/jboss/docs/jms/bin you will find Unix shell scripts and Microsoft batch files made available to make it easier to see the files that have to be included in the classpath.

Most stuff is hardcoded and all the files that contain some code that differs from the code for JBoss version 2.2.x will be named with the applicable JBoss version. This might be a Java source file, a deployment descriptor or a shell script.