JMS Postcard

JMS Postcard is a simple, friendly way to do the following:

Verify that you have successfully installed WebSphere MQ and WebSphere MQ JMS on one computer and, optionally, others as well
Introduce you to messaging

You must make sure that the Java Messaging feature of WebSphere MQ for Windows (WebSphere MQ JMS) is installed to be able to use JMS Postcard. In turn, WebSphere MQ JMS requires that you have a working Java Runtime Environment (JRE) at Java 1.3 level.

Before you can successful run the JMS Postcard application, you must have defined the environment variables CLASSPATH, LIBPATH, MQ_JAVA_INSTALL_PATH, and MQ_JAVA_DATA_PATH. On Windows systems these variables are set as part of the install process. On other platforms you must set them yourself. For more information about these variables, see Environment variables.

Many operations that the Postcard application carries out on your behalf require the user to be a member of the WebSphere MQ administrators group (mqm). If you are not a member of mqm, get a member of the mqm group to set up the default configuration on your behalf. See JMS Postcard default configuration.

Starting

To start the JMS Postcard application, run the postcard script. This is supplied in the java/bin directory of the WebSphere MQ installation.

The first time JMS Postcard is run on a computer, you are asked to complete the default configuration, which sets up a suitable queue manager to act as mailbox. See JMS Postcard default configuration.

Whenever you start a Postcard application, you are asked to sign on and enter a nickname. (There are advanced options available on the sign-on dialog, see Signon advanced options for details).

Signon

The sign-on dialog has a check box labelled Advanced. Check this to see the extended dialog where you can choose which queue manager is used by the Postcard program.

Notes:

If you have no queue managers at all, or just the default configuration, then the checkbox will be disabled.
Depending upon what queue managers and clusters you have, the checkbox and options will be in one of various combinations of enabled, disabled, and preselected.

Signon advanced options

Use default configuration as mailbox

This is the easiest way to use JMS Postcard, on one or several computers. Make sure that the default configuration is installed on all the computers, that one of them holds the repository, and all the others use the first one as their repository; this puts them all in the same cluster.

Choose queue manager as mailbox

Use the drop-down list to choose any one of your local queue managers. If you want to send postcards between two queue managers (on one or more computers) this way, then it is up to you to make sure that one of the following conditions is true:

The queue managers are in the same cluster (for more information about clusters, see the WebSphere MQ Queue Manager Clusters book).
There are explicit connections between the queue managers.

Sending a postcard

To send a postcard successfully, you need to have two instances of the Postcard application with different nicknames. For example, suppose you start the Postcard application and use the nickname "Will", and then start it again using the nickname "Tim". Will can send postcards to Tim and Tim can send postcards to Will.

If Will and Tim are connected to the same queue manager, see Running JMS Postcard with one queue manager.

If Tim is on a different queue manager manager (on the same or a different computer from Will), see Running JMS Postcard with two queue managers.

When the postcard arrives successfully, you know your WebSphere MQ installation and your WebSphere MQ JMS are working correctly.

For an alternative means of verifying installation of WebSphere MQ JMS, run the IVTRun application from the command line. See Running the point-to-point IVT for more information about this.

Running JMS Postcard with one queue manager

This assumes that you have already started the Postcard application with a nickname, for example "Will", and you want to send a postcard to a second nickname on this computer. Follow these steps:

Move the first Postcard (Will) to one side of your screen, then start a second Postcard by running the postcard shell script again.
Enter your second nickname, for example "Tim".
On Will's Postcard fill in the To field with your second nickname, Tim. (You can leave the On field empty and Postcard will fill it in for you, or you can type in the queue manager name that you see below the Message box after On).
Click in the Message box, type your message in, and click the Send button.
Look in Tim's Postcard to see the message arrive, and double-click on it to see the postcard itself.
Try using Tim to send a message back to Will. You can do this easily, by selecting the message that arrived in Tim's list, and clicking the Reply button.

Note:: See JMS Postcard configuration for advice about configuration.

Running JMS Postcard with two queue managers

This assumes that you have already started JMS Postcard with a nickname, for example "Will", and you want to send a postcard to a second nickname on a second queue manager on this, or another, computer.

Start the second Postcard, choosing one of the following:
- JMS Postcard
  - on this computer:
    run the postcard shell script again, then in the sign-on dialog check Advanced and select the second queue manager you want to use.
  - on another computer:
    run the postcard shell script; or, on Windows systems, open WebSphere MQ First Steps and click on JMS Postcard.
- MQI Postcard on Windows systems:
  either start from WebSphere MQ First Steps (to use the default configuration), or open the WebSphere MQ Explorer, right-click on the queue manager you want to use and select All Tasks->Start a Postcard...
When the sign-on dialog appears, enter your second nickname (for example, "Tim").
In the Postcard application on Will's computer, fill in the To field with your second nickname (Tim), and in the On field put the queue manager name of the second postcard where Tim is (if you don't know this name, on Tim's computer in the Postcard look below the Message box after On:; alternatively if both queue managers are in the default configuration cluster you can just type in the short TCP/IP name of Tim's computer and Postcard will build that into the queue manager name in the same way that the task which creates the default configuration does).
Type your message in, and click the Send button.
Look in Tim's Postcard to see the message arrive, and double-click on it to see the postcard itself.
Try sending a message from Tim's computer back to Will.
You can do this easily, by selecting the message that arrived in Tim's list, and clicking the Reply button.

Note:: See JMS Postcard configuration.

JMS Postcard configuration

The Postcard application needs a suitable queue manager to act as mailbox. See JMS Postcard default configuration for the easiest way to get one. You will be prompted to install this default configuration the first time you start the Postcard application (see Starting).

Instead of using the default configuration, you can also start the Postcard application using any other local queue manager.

If you want to send postcards to another computer, or to other queue managers, the default configuration must include the option of being joined in the same cluster. The other queue managers must either be in the same cluster or you must create a connection explicitly between them.

JMS Postcard default configuration

Installing the default configuration quickly and easily creates a special queue manager (with queues and channels), and optionally joins it to a cluster, to enable you to use the JMS Postcard application to verify your installation and see messaging working.

On WebSphere MQ for Windows, the Default Configuration Wizard will automatically open when JMS Postcard is started and the wizard has not already been run on this computer.

On platforms other than Windows systems, you can also run the DefaultConfiguration script, provided that there are no existing queue managers on this computer. On Windows systems, run Default Configuration from First Steps.

Note:: You need to be a member of the WebSphere MQ administrators group (mqm) to complete default configuration successfully. If you are not a member of mqm, get a member of the mqm group to set up the default configuration on your behalf.

How JMS Postcard works

Starting up

When JMS Postcard starts, it checks to see what queue managers exist on this computer, and initializes the sign-on dialog accordingly. If there are no queue managers at all, it will prompt you to install the default configuration.

JMS Postcard uses the Java Message Service method queueConnectionFactory.createQueueConnection() to connect to the default queue manager.

Receiving messages

All the time JMS Postcard is running, it polls a queue called postcard for incoming messages from other Postcard applications. If there is no queue called postcard, JMS Postcard will attempt to create one.

When JMS Postcard starts running, it creates a Java Message Service QueueReceiver object for the local postcard queue, providing as a parameter a selector string which filters the messages to be received from the queue by the Correlation Identifier (CorrelId field). The selector string defines that the postcard client should only receive messages where the CorrelId field matches the nickname of the user. The words from the message data are then presented in the JMS Postcard window.

Sending messages

If you did not enter a computer name in the On: field, then JMS Postcard assumes the recipient is on the same queue manager.

If you did enter a name, postcard checks for the existence of a queue manager with this name - first using the exact name supplied, and then using a prefix in the same format as that created by the default configuration.

In both cases, it issues a session.createQueue('postcard'), and sets the base queue manager name to the string supplied.

Finally it builds a JMS BytesMessage from your nickname and the words you typed in, and runs queueSender.send(theMessage) to put the message onto the queue.

How the postcards get there

When other instances of Postcard on this computer are using the same queue manager and queue, the messages are simply being put and got from the one queue. This does, however, verify that the WebSphere MQ code installed on this computer is configured and working correctly.

JMS Postcard can only send to another queue manager if a connection to that queue manager exists. This connection will exist because either both queue managers are members of the same cluster, or you have explicitly created a connection yourself. JMS Postcard can therefore assume that the queue manager will be connectable, and simply connects to it, opens the queue and puts a message, as already described, leaving all the work of getting the message there to the WebSphere MQ cluster code. In other words, JMS Postcard uses only the one piece of code for putting the message, and does not need to know whether or not the message is going to another computer.

In JMS Postcard, when session.createSender('postcard') is called, the cluster code checks the repository to find the other queue manager, and to check that the queue exists, and throws an exception if this was not possible for any reason.

When queueSender.send(theMessage) is called, the cluster code opens a channel to the other queue manager (creating it if necessary) and sends the message.

The channel may be discarded afterwards, if the cluster optimizing code does not need it. If the queue managers are on different computers, that is all handled by the cluster code.

Tidying up undeliverable messages

If you sent a postcard message to "John", but never ran a Postcard application with the nickname "John", the message would sit on the queue for ever. To prevent this, JMS Postcard sets the Message Lifetime (Expiry) field in the Message Descriptor (MQMD) to 48 hours. After that time, the message will be discarded, wherever it may be (possibly even still in transmission).

Exchanging messages between different WebSphere MQ Postcard applications

You can exchange messages between all the different types of Postcard application as follows:

MQI Postcard on WebSphere MQ for Windows.
JMS Postcard on Windows systems.
JMS Postcard on other operating systems such as UNIX.
MQSeries Postcard on previous versions of MQSeries for Windows, with the exception that it cannot receive messages from JMS Postcard.
MQ Everyplace Postcard on WebSphere MQ Everyplace on pervasive devices. For this a connection must be explicitly set up between the queue managers. See the WebSphere MQ Everyplace product documentation for further information.

Customizing JMS Postcard

Normally JMS Postcard uses standard Java Swing settings for font size and background color. But if a postcard.ini file is detected on startup, JMS Postcard will use settings specified in this file instead. You can also change the trace setting.

Edit the sample file postcard.ini in the bin directory of the WebSphere MQ classes for Java installation and set your preferred settings for font size, and screen foreground and background colors.

Note:: The precise use of upper and lower case letters in the keywords, as in the following examples, must be strictly observed when you set these properties.

Setting screen colors

By setting the Background and Foreground properties, you can change the background and foreground colors of controls used in the Postcard application.

Background=000000
Foreground=FFFFFF

This example selects white text on a black background. The values represent intensity levels for Red, Green, and Blue colors using a hexadecimal scale from 00 to FF. Other examples of colors are FF0000 (bright red), 00FF00 (bright green) and 0000FF (bright blue).

Setting font size

MinimumFont=20

This example selects a minimum font size of 20 points. Any value smaller than 13 is ignored.

Using an external browser for online help

WebBrowser=nautilus

This setting is only applicable on non-Windows systems. The internal browser used for displaying online help information cannot be customized. This setting allows you to identify an alternative browser.

Tracing the Postcard application

Trace=1

Set this to start trace output. Note that the trace output is sent to the trc subdirectory of the directory defined by the MQ_JAVA_DATA_PATH system environment variable. If the application cannot write to this directory, trace output is directed to the system console.

You can also use the MQJMS_TRACE_LEVEL parameter on the java command line to start tracing. See Tracing programs for more about tracing applications.