JMQ Notification Messages and Properties

This page contains the following topics:

For related topics on JMQ notification, see the following pages:

• Enabling JMQ Notification (Example)
• JMQ Notification Overview
• Configuring a JMQ Notification Service (Tasks and Examples)

Notification Messages

Notification messages can be generated for various kinds of events that occur in the message store. For example, when a user logs in, a Login message can be produced and delivered to the Message Queue broker.

A configutil parameter specifies each kind of message to be produced. You determine which events will generate messages by configuring various configutil parameters. The configutil parameters are referenced by one or more JMQ Notification plug-in libraries.

All messages are delivered to a topic or a queue, depending on whether the destination type is set to "topic" or "queue". For information on how to configure the Message Queue destination, see To Configure a JMQ Notification Plug-in.

Each message is identified by the following message header:

MQ_MESSAGE_TYPE_HEADER_PROPERTY

The JMQ Notification plug-in supports the messages shown in the following table.

For a list of the configutil parameters that enable these messages, see Default Values of the configutil Parameters.

Table 22-1 JMQ Notification Messages

Rules and Guidelines for Notification Messages

The following rules and guidelines apply to the supported notification messages:

• The text of most notification messages is a single blank space. (The blank space is used because Message Queue does not permit an empty message body.) The exceptions are as follows:
  
  • The NewMsg, UpdateMsg, and DeleteMsg messages can include a message header when configured with the maxHeaderSize parameter. You must set maxHeaderSize to a value greater than zero.
    To include a message header with a DeleteMsg message, you also must set the ExpungeHeaders parameter to a value of 1.
    
  • NewMsg and UpdateMsg message can include a message body when configured with the maxBodySize parameter. You must set maxBodySize to a value greater than zero.
    For NewMsg and UpdateMsg, by default the message body is not delivered (is turned off). This prevents overloading Message Queue. No other messages include a message body.
    
• Notification messages can be generated for changes to the INBOX alone, or to the INBOX and all other folders. The following configuration parameter allows for INBOX only (value = 0), or for both the INBOX and all other folders (value = 1):
  

  local.store.notifyplugin._jmqnotify_.noneInbox.enable
  

  The default setting is to generate messages from the INBOX only (value = 0).
  There is no mechanism to select folders; all folders are included when the variable is enabled (value = 1).
  

• The NewMsg notification is issued only after the message is deposited in the user mailbox (as opposed to “after it was accepted by the server and queued in the message queue”).
  
• Messages are not generated for POP3 client access.
  
• All messages can be suppressed by issuing XNOTNOTIFY. For example, an IMAP script used for housekeeping only (the users are not meant to be notified) might issue it to suppress all messages.
  

Notifications for Particular Message Types

Notifications can deliver status information about messages of different types, such as text messages, voice mail, and image data. Users often expect these heterogeneous message types to be stored in the same mail folder. For example, a user may want new text messages and voice mail to arrive in the user's cell phone inbox.

To configure these message types, you use configutil commands such as store.messagetype.enable. For information about configuring and managing message types, see “Managing Message Types” in “Chapter 18: Managing the Message Store.”

Once the message types have been configured, JMQ notification messages can identify the particular message types. You can write your Message Queue client to interpret notification messages by message type and deliver status information about each type to the mail client.

For example, suppose new messages of different types arrive in a user's mailbox. A NewMsg notification message can carry data to tell the user that, for example, there are seven new voice mail messages and four new text messages in the user's inbox.

The following notification messages can carry information that tracks particular message types:

NewMsg
UpdateMsg
ReadMsg
TrashMsg
DeleteMsg
PurgeMsg
OverQuota
UnderQuota

The JMQ notification function counts the number of messages currently in the mailbox, by message type. Instead of sending one count, an array specifying the count for each message type is sent with the notification message.

The message-specific count is carried in the numMsgs property and delivered with the notification message. For ReadMsg and TrashMsg notification messages, the number of messages seen (numSeen) and the number marked as deleted (numDeleted) are also counted by message type.

Note - The Event Notification Service does not support message types. Use a JMQ notification plug-in to deliver information about message types.

Default Values of the configutil Parameters

The notification messages and the configuration information needed by Message Queue are configured with configutil parameters.

Table 22-2 shows these parameters and their default values.

For complete definitions of the configutil parameters, see Messaging Server Configuration.

Table 22-2 configutil Parameters and Their Default Values

Notification Message Properties

Every message carries additional information defined in properties. Different properties are present for different messages. For example, NewMsg indicates the IMAP uid of the new message.

Standard Notification Message Properties

Table 22-3 describes the standard notification message properties. These properties are present in all JMS messages.

Table 22-3 Standard Notification Message Properties

Properties Specific to Particular Notification Messages

Table 22-4 describes the properties carried with particular notification messages.

Each message includes a subset of the properties shown in the table below. For a list of the properties associated with each message, see Table 22-5.

Table 22-4 Properties Specific to Particular Notification Messages

Note - Subscribers should allow for undocumented properties when parsing the message reference. This allows for future compatibility when new properties are added.

Syntax for newflags and oldflags Properties

The newflags and oldflags properties are 5–character strings. The string must have the following values:

• If the /answered flag is set, the first character is "A". If not, it is blank (“ “).
  
• If the /flagged flag is set, the second character is "F". If not, it is blank (“ “).
  
• If the /deleted flag is set, the third character is "D". If not, it is blank (“ “).
  
• If the /seen flag is set, the fourth character is "S". If not, it is blank (“ “).
  
• If the /draft flag is set, the fifth character is "R". If not, it is blank (“ “).
  

Properties Carried with Each Notification Message

Table 22-5 shows the properties associated with each notification message.

For example, to see which properties apply to a TrashMsg message, look in the column header for “ReadMsg, TrashMsg.” A TrashMsg message can use mailboxName, numMsgs, uidValidity, numSeen, and numDeleted (in addition to the standard properties).

Table 22-5 Properties Carried with Each Notification Message

Note - The numDeletedn, numMsgsn, numSeenn, and numSeenDeletedn properties are carried with notifications only if message types are defined in the message store.