JMS Postcard

 

JMS Postcard is a simple way to do the following:

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

  • Introduce you to messaging

Note:
JMS Postcard is not supported on WebSphere MQ for z/OS or WebSphere MQ for iSeries.

 

Setting up JMS Postcard

To use JMS Postcard, make sure that the Java Messaging feature of WebSphere MQ for Windows (WebSphere MQ JMS) is installed. You also need a working JRE at Java 1.3 level.

Before you can successfully run the JMS Postcard application, define 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 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 that you run JMS Postcard, it asks you 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, sign on and enter a nickname. (There are advanced options available on the sign-on dialog, see Sign-on advanced options for details).

 

Sign-on

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:

  1. If you have no queue managers at all, or just the default configuration, the checkbox is disabled.

  2. Depending on what queue managers and clusters you have, the checkbox and options are in one of various combinations of enabled, disabled, and preselected.

 

Sign-on 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 that 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, 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 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 that your WebSphere MQ installation and WebSphere MQ JMS are working correctly.

For an alternative way of verifying the 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

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

  1. Move the first Postcard (Will) to one side of your screen, then start a second Postcard by running the postcard shell script again.

  2. Enter your second nickname, for example Tim.

  3. 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).

  4. Click in the Message box, type your message in, and click the Send button.

  5. Look in Tim's Postcard to see the message arrive, and double-click on it to see the postcard itself.

  6. Try using Tim to send a message back to Will. You can do this 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

If 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, follow these steps:

  1. 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 click All Tasks->Start a Postcard...

  2. When the sign-on dialog appears, enter your second nickname (for example, Tim).

  3. 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 builds that into the queue manager name in the same way that the task that creates the default configuration does.

  4. Type your message, and click Send.

    Look in Tim's Postcard to see the message arrive, and double-click on it to see the postcard itself.

  5. Try sending a message from Tim's computer back to Will.

    You can do this by selecting the message that arrived in Tim's list, and clicking Reply.

Note:
See JMS Postcard configuration.

See also How JMS Postcard works.

 

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 create a connection explicitly between them.

See also How JMS Postcard works.

 

JMS Postcard default configuration

Installing the default configuration 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 automatically opens 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 must 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

This section tells you how the JMS Postcard works, including:

 

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 prompts 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 creates 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 that 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, JMS Postcard assumes that the recipient is on the same queue manager.

If you entered a name, JMS 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 use the same queue manager and queue, the messages are 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 exists 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 it can connect to the queue manager, and 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 one piece of code for putting the message, and does not need to know whether 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.

Discard the channel 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 is 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 and 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 it detects a postcard.ini file on startup, JMS Postcard uses 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.

 

WebSphere is a trademark of the IBM Corporation in the United States, other countries, or both.

 

IBM is a trademark of the IBM Corporation in the United States, other countries, or both.