Sun Java System Messaging Server 6.3 Administration Guide

22.2 Configuring a JMQ Notification Service

This section briefly describes how a JMQ notification plug-in fits into the context of a complete Message Queue service. It then provides detailed instructions for configuring a JMQ notification plug-in.

22.2.1 Planning for Your JMQ Notification Service

A JMQ notification plug-in is only one part of a Message Queue service. A messaging service also includes clients that consume the messages and the Message Queue infrastructure (the broker, administration components, and so on).

The following steps outline the tasks you should perform to create a Message Queue service that supports Messaging Server:

Design your notification message service.

Define the notification messages needed for your Messaging Server installation. The planning and design phases of your message-service development lifecycle lie outside the scope of this chapter. However, you should answer the following design questions before you configure the JMQ notification plug-in:
- Which message events do you need to produce notifications? For a list of the available notification messages, see 22.3.1 Notification Messages.
- Do you intend to produce messages to a queue, a topic, or both?
- Do you intend to use the proprietary Event Notification Service as well as the Message Queue service?
The answers to these questions will help you decide whether to configure one notification plug-in or multiple plug-ins, and to determine how to configure each plug-in.
Install, configure, and deploy the Message Queue product.

For information about installing Message Queue, see the Sun Java System Message Queue Installation Guide.

For information about configuring and deploying Message Queue, see the Sun Java System Message Queue Administration Guide.
Write one or more Message Queue clients that will consume the JMQ notification messages.

The clients must conform to the requirements for a Message Queue client API. A simple example of client source code, written in C, is available in the following path:
/opt/SUNWmsgsr/examples/jmqsdk/
The source file name is jmqclient.c.

This client source code receives messages from the JMQ notification messages defined by the parameters in the libjmqnotify library. It then sends the message output to stdout.

For information about writing Message Queue clients in C or Java, see the Sun Java System Message Queue Developer's Guide for C Clients or the Sun Java System Message Queue Developer's Guide for Java Clients.
Configure and enable the JMQ notification plug-in for producing notification messages.

The remainder of this chapter describes how to configure the notification plug-in.
Configure and start the runtime Message Queue clients.

For information about deploying the runtime Message Queue clients, see the Sun Java System Message Queue Administration Guide.

To Configure a JMQ Notification Plug-in

In this procedure, you first configure the message events that will produce notifications. Next, you specify the information needed by Message Queue. Finally (in step 9), you configure the plug-in name by specifying a parameter after the name of the plug-in library:

'/opt/SUNWmsgsr/lib/libjmqnotify$plug-in_name'

If you do not specify a plug-in name, jmqnotify is used by default.

Before You Begin

You should install, configure, and deploy the following products:

Sun Java System Messaging Server
Sun Java System Message Queue 3.6 SP3 2005Q4 or later

Note –

Most of the configutil parameters you will configure in the following steps are optional. For a list of their default values, see Table 22–2.

Configure the notification message parameters.

For each kind of notification message you want to include in the plug-in, use the local.store.notifyplugin command with the configutil utility.

For example, to enable notifications for new messages, enter:
configutil -o local.store.notifyplugin.jmqnotify.NewMsg.enable -v 1
where jmqnotify is the name of the plug-in

and -v 1 enables notifications for this message. A value of 0 disables notifications for this message.

For a list of all the JMQ notification messages, see 22.3.1 Notification Messages.

For definitions of the configutil parameters that enable the JMQ notification messages, see “Chapter 3: Messaging Server Configuration,” in the Sun Java System Messaging Server Administration Reference.

A few notification messages use more than one configutil parameter to enable the message with additional features. For example, some messages can carry message headers in the notification text. For instructions on how to configure these messages, see Syntax for newflags and oldflags Properties.

Note –
You must configure parameters separately for each plug-in you configure.

Thus, if you configure two plug-ins, named jmq1 and jmq2, and you want to enable new-message notifications for both plug-ins, you must run the local.store.notifyplugin command twice:
configutil -o local.store.notifyplugin.jmq1.NewMsg.enable -v 1
configutil -o local.store.notifyplugin.jmq2.NewMsg.enable -v 1

Specify the host where the Message Queue destination (broker) is running.

For example, enter the following command:
configutil -o local.store.notifyplugin.jmqnotify.jmqHost -v "127.0.0.1"
where jmqnotify is the name of the plug-in

and "127.0.0.1" is the IP address of the host machine for the Message Queue broker.

Specify the port for the Message Queue broker.

For example, enter the following command:
configutil -o local.store.notifyplugin.jmqnotify.jmqPort -v "7676"
where jmqnotify is the name of the plug-in

and "7676" is the port for the Message Queue broker.

Specify the user ID and password of the Message Queue user authorized to produce messages to the service.

For example, enter the following commands:
configutil -o local.store.notifyplugin.jmqnotify.jmqUser -v "guest"
configutil -o local.store.notifyplugin.jmqnotify.jmqPwd -v "%$#a62t&"
where jmqnotify is the name of the plug-in

and "guest" and "%$#a62t&" are the user ID and password, respectively, for the Message Queue user.

Configure the type of destination (topic or queue) and the name of the destination to which messages will be sent.

Follow these steps:
1. Specify whether the destination is a topic or queue.
  
  For example, enter the following command:
  configutil -o local.store.notifyplugin.jmqnotify.DestinationType -v "queue"
  where jmqnotify is the name of the plug-in
  
  and "queue" specifies that the destination is a queue. The allowed values for this parameter are "queue" and "topic".
2. Specify the destination name.
  
  For example, enter one of the following commands:
  configutil -o local.store.notifyplugin.jmqnotify.jmqQueue -v "JES-MS"
  or
  configutil -o local.store.notifyplugin.jmqnotify.jmqTopic -v "JES-MS"
  where jmqnotify is the name of the plug-in
  
  jmqQueue or jmqTopic identifies the destination type. The jmqQueue and jmqTopic parameters are synonymous and mutually exclusive; you can only use one of these parameters in one plug-in.
  
  "JES-MS" is an example name of the queue or topic to which messages will be sent.

Specify the message priority.

For example, enter the following command:
configutil -o local.store.notifyplugin.jmqnotify.Priority -v 3
where jmqnotify is the name of the plug-in

and -v 3 is the Message Queue priority assigned to messages produced by this plug-in.

The default value of the Priority is 4.

Specify the length of time (in milliseconds) that messages are retained by the Message Queue broker.

For example, enter the following command:
configutil -o local.store.notifyplugin.jmqnotify.ttl -v 100
where jmqnotify is the name of the plug-in

and -v 100 specifies that a message is retained by the Message Queue service for 100 milliseconds before being either delivered or discarded. A value of 0 means that a message is retained permanently; it does not time out.

Specify the message persistence.

For example, enter the following command:
configutil -o local.store.notifyplugin.jmqnotify.Persistent -v 1
where jmqnotify is the name of the plug-in

and -v 1 specifies that persistent messages are used in the Message Queue service. Allowed values are 1 (persistent) and 0 (non-persistent).

Configure the plug-in name.

To configure a single plug-in with the default name, you can enter either the fully qualified name of the plug-in library or the name of the library and its plug-in parameter:
configutil -o local.store.notifyplugin -v /opt/SUNWmsgsr/lib/libjmqnotify
or
configutil -o local.store.notifyplugin -v '/opt/SUNWmsgsr/lib/libjmqnotify$jmqnotify'
where libjmqnotify is the library name

and jmqnotify is the default name of the plug-in parameter.

Use the dollar sign ($) to separate the library name from the parameter.

Enclose the entire value in single quotes ('value'); if you do not, the shell will interpret the dollar sign.

The configutil parameters read by the default plug-in have the following names:
local.store.notifyplugin.jmqnotify.*
To configure a different plug-in name such as jmq42, you would enter the following command:
configutil -o local.store.notifyplugin -v '/opt/SUNWmsgsr/lib/libjmqnotify$jmq42'
The configutil parameters read by the jmq42 plug-in have the following names:
local.store.notifyplugin.jmq42.*

To Configure Multiple Plug-ins

Configure a separate set of JMQ notification parameters for each plug-in you intend to create.

For example, suppose you configure two plug-ins named jmq1 and jmq2. Assume you want to enable new-message notifications for both plug-ins and purged-message notifications for the jmq2 plug-in only. In this case, you would run the local.store.notifyplugin command three times, as follows:
configutil -o local.store.notifyplugin.jmq1.NewMsg.enable -v 1
configutil -o local.store.notifyplugin.jmq2.NewMsg.enable -v 1
configutil -o local.store.notifyplugin.jmq2.PurgeMsg.enable -v 1
You also must specify parameters that enable the plug-ins to communicate with the Message Queue service.

For step-by-step instructions for configuring the all the notification parameters, see To Configure a JMQ Notification Plug-in.

Configure the plug-in names.

To configure two plug-ins named jmq1 and jmq2, you would enter the following command:
configutil -o local.store.notifyplugin -v '/opt/SUNWmsgsr/lib/libjmqnotify$jmq1$$/opt/SUNWmsgsr/ \ lib/libjmqnotify$jmq2'
In this example, two instances of the plug-in library are run.

Use a single dollar sign ($) to separate the library name from the parameter that specifies the plug-in name.

Use two dollar signs ($$) to separate the first plug-in instance from the next one.

Enclose the entire value in single quotes ('value'); if you do not, the shell will interpret the dollar signs.

In this example, the first instance builds its configuration from parameters with the name jmq1:
local.store.notify.jmq1.*
The second instance builds its configuration from parameters with the name jmq2:
local.store.notify.jmq2.*

22.2.2 Specifying Notification Messages that Use More Than One `configutil` Parameter

For most notification messages, you specify the message by running a single local.store.notifyplugin command.

However, the following notification messages are (or can be) configured with more than one local.store.notifyplugin command:

NewMsg
UpdateMsg
DeleteMsg
MsgFlags

The procedures that follow describe how to set up these notification messages.

To Configure New-Message and Updated-Message Notifications with Message Headers and Message Bodies

You can add the message headers and message bodies to the text of notification messages sent when there are new or updated email messages.

Including message headers and message bodies is optional; you can include both features, one feature only, or neither feature. The default is to send messages without message headers or message bodies.

Specify the new-message or updated-message notification:
configutil -o local.store.notifyplugin.jmqnotify.NewMsg.enable -v 1
configutil -o local.store.notifyplugin.jmqnotify.UpdateMsg.enable -v 1
where jmqnotify is the name of the plug-in

and -v 1 enables notifications for these messages. A value of 0 disables notifications.

Specify the maxHeaderSize parameter with a value greater than zero, as in the following example:
configutil -o local.store.notifyplugin.jmqnotify.maxHeaderSize -v 1024
where jmqnotify is the name of the plug-in

and 1024 is the maximum size of the header to be sent. The default value of maxHeaderSize is 0, which sends no header information with the message.

Specify the maxBodySize parameter with a value greater than zero, as in the following example:
configutil -o local.store.notifyplugin.jmqnotify.maxBodySize -v 1024
where jmqnotify is the name of the plug-in

and 5120 is the maximum size of the message body to be sent. The default value of maxBodySize is 0, which sends no body with the message.

To Configure Deleted-Message Notifications with Message Headers

You can add the message headers to the text of notification messages sent when email messages are deleted.

Including message headers is optional. The default is to send notifications without message headers.

Enable notifications to be sent when email messages are deleted:
configutil -o local.store.notifyplugin.jmqnotify.DeleteMsg.enable -v 1
where jmqnotify is the name of the plug-in

and -v 1 enables notifications for this message. A value of 0 disables notifications.

Specify the ExpungeHeaders parameter:
configutil -o local.store.notifyplugin.jmqnotify.ExpungeHeaders -v 1
where jmqnotify is the name of the plug-in

and -v 1 enables message headers to be carried with deleted-message notifications. The default value of ExpungeHeaders is 0, which prohibits deleted-message notifications from carrying header information.

You must configure the ExpungeHeaders parameter to enable DeleteMsg messages to carry message headers.

Specify the maxHeaderSize parameter with a value greater than zero, as in the following example:
configutil -o local.store.notifyplugin.jmqnotify.maxHeaderSize -v 1024
where jmqnotify is the name of the plug-in

and 1024 is the maximum size of the header to be sent. The default value of maxHeaderSize is 0, which sends no header information with the message.

22.2.2.1 Configuring Notifications for Changes in Message Status

You can configure a notification message to be sent when an email message has changed status.

Information Delivered in Message-Flag Notifications

A message-flags notification is produced whenever a status flag has changed because the email message was:

Answered
Flagged
Deleted
Seen (read)
Draft

When a message-flags notification is sent, the notification carries the following properties:

The flags set for the email message before its status changed
The flags set for the email message after its status changed

This information is carried in two properties, oldflags and newflags, which are 5–character strings.

For a description of the values of these two properties, see Syntax for newflags and oldflags Properties.

Configutil Parameters Needed for Message-Flag Notifications

To enable message-flag notifications, you must configure the following configutil parameters:

local.store.notifyplugin.MsgFlags
local.store.notifyplugin.*.MsgFlags.enable

The first MsgFlags parameter enables the IMAP server and message store to identify and track the changing values of the status flags so that this information can be delivered in notification messages.

This parameter applies to all notification plug-ins. Therefore, you must enable the parameter if any notification plug-in uses message-flag notifications. If no plug-in uses message-flag notifications, be sure that this parameter is disabled (its default value).

The second parameter, *.MsgFlags.enable, allows message-flag notifications to be sent for a particular plug-in library.