22.3 JMQ Notification Messages and Properties
This section describes the following topics:
22.3.1 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 22.3.4 Default Values of the configutil Parameters.
Table 22–1 JMQ Notification Messages|
Notification Message |
Description |
|---|---|
|
DeleteMsg |
Messages marked as “Deleted” are removed from the mailbox. This is the equivalent to IMAP expunge. |
|
Login |
User logged in from IMAP, HTTP, or POP. (This message is enabled with the configutil parameter local.store.notifyplugin.*.LogUser.enable.) |
|
Logout |
User logged out from IMAP, HTTP, or POP. (This message is enabled with the configutil parameter local.store.notifyplugin.*.LogUser.enable.) |
|
MsgFlags |
Message flags on a message have been changed. The old and new flags are carried with this message. |
|
NewMsg |
New message was received by the system into the user’s mailbox. Can contain message headers and body. |
|
OverQuota |
Operation failed because the user’s mailbox exceeded one of the quotas (diskquota, msgquota). The MTA channel holds the message until the quota changes or the user’s mailbox count goes below the quota. If the message expires while it is being held by the MTA, it will be expunged. |
|
PurgeMsg |
Message expunged (as a result of an expired date) from the mailbox by the server process imexpire. This is a server side expunge, whereas DeleteMsg is a client side expunge. This is not a purge in the true sense of the word. |
|
ReadMsg |
Message in the mailbox was read. (In the IMAP protocol, the message was marked Seen.) |
|
TrashMsg |
Message was marked for deletion by IMAP or HTTP. The user may still see the message in the folder, depending on the mail client’s configuration. The messages are to be removed from the folder when an expunge is performed. |
|
UnderQuota |
Quota went back to normal from OverQuota state. |
|
UpdateMsg |
Message was appended to the mailbox by an IMAP operation. For example, the user copied an email message to the mailbox. Can contain message headers and body. |
22.3.2 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.
22.3.3 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.
22.3.4 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 “Chapter 3: Messaging Server Configuration,” in the Sun Java System Messaging Server Administration Reference.
Table 22–2 configutil Parameters and Their Default Values|
configutil Parameter |
Default Value |
|---|---|
|
local.store.notifyplugin.*.maxBodySize |
0 — Disabled |
|
local.store.notifyplugin.*.maxHeaderSize |
0 — Disabled |
|
local.store.notifyplugin.*.NewMsg.enable |
1 — Enabled |
|
local.store.notifyplugin.*.UpdateMsg.enable |
1 — Enabled |
|
local.store.notifyplugin.*.ReadMsg.enable |
1 — Enabled |
|
local.store.notifyplugin.*.DeleteMsg.enable |
1 — Enabled |
|
local.store.notifyplugin.*.PurgeMsg.enable |
1 — Enabled |
|
local.store.notifyplugin.*.LogUser.enable |
1 — Enabled |
|
local.store.notifyplugin.*.MsgFlags.enable |
0 — Disabled |
|
local.store.notifyplugin.*.noneInBox.enable |
0 — Disabled |
|
local.store.notifyplugin.*.jmqHost |
“127.0.0.1” |
|
local.store.notifyplugin.*.jmqPort |
7676 |
|
local.store.notifyplugin.*.jmqTopic |
“JES-MS” |
|
local.store.notifyplugin.*.jmqQueue |
“JES-MS” |
|
local.store.notifyplugin.*.jmqUser |
“guest” |
|
local.store.notifyplugin.*.jmqPwd |
“guest” |
|
local.store.notifyplugin.*.destinationtype |
“topic” |
|
local.store.notifyplugin.*.Priority |
4 |
|
local.store.notifyplugin.*.ttl |
0 — Indicates that messages never time out. |
|
local.store.notifyplugin.*.Persistent |
1 — Enabled |
22.3.5 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.
22.3.5.1 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|
Property |
Data Type |
Description |
|---|---|---|
|
hostname |
ConstMQString |
The host name of the machine that generated the message. |
|
pid |
MQInt32 |
ID of the process that generated the message. |
|
process |
ConstMQString |
Specifies the name of the process that generated the message. |
|
timestamp |
MQFloat64 |
Specifies the number of milliseconds since the epoch (midnight GMT, January 1, 1970). |
22.3.5.2 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|
Property |
Data Type |
Description |
|---|---|---|
|
client |
ConstMQString |
The IP address of the Message Queue client associated with the message. |
|
diskquota |
MQInt32 |
The disk space quota, in kilobytes, for the user associated with the message. The value is set to -1 to indicate no quotas. |
|
diskquotaused |
MQInt32 |
The amount of disk space used by the user associated with the message, in kilobytes. |
|
hdrLen |
MQInt32 |
The size of the message header. Note that this might not be the size of the header in the message body, because it might have been truncated. |
|
imapUid |
MQInt32 |
The IMAP uid property associated with the message. |
|
lastUid |
MQInt32 |
The last IMAP uid value used in the mailbox. |
|
mailboxName |
ConstMQstring |
The message-store mailbox name associated with the event. The mailboxName has one of the following formats (where uid is the user's unique identifier): uid — identifies the inbox of a user in the default (primary) domain. uid@domain — identifies the inbox of a user in a hosted domain. uid/mailboxname — identifies the top-level mailbox of a user in the default domain. uid@domain/mailboxname — identifies the top-level mailbox of a user in a hosted domain. uid/foldername/mailboxname — identifies a mailbox in a folder of a user in the default domain. uid@domain/foldername/mailboxname — identifies a mailbox in a folder of a user in a hosted domain. |
|
msgquota |
MQInt32 |
The user's quota for the maximum number of messages. The value is set to -1 to indicate no quotas. |
|
newflags |
ConstMQString |
The flags set for the user's mailbox message after they were changed by the current operation. This property is always present, together with oldflags, when a MsgFlags notification message is produced. For the syntax and values for newflags, see Syntax for newflags and oldflags Properties, below this table. |
|
numDeleted |
MQInt32 |
The number of messages in the mailbox marked as deleted. This number counts the messages deleted by the mailbox owner. If other users have access to the mailbox, their actions in the mailbox are not included in this count. (However, the other users' actions can trigger notifications such as DeleteMsg). |
|
numDeletednn |
MQInt32 |
The total number of messages in the mailbox marked as deleted, specified for each message type. If message types are configured, a numDeletednn property carries a count for each message type nn. The numDeleted property is always sent; it counts the total number of all messages marked as deleted, including all types. For example, if 20 messages are marked as deleted, 10 are of type 3, 7 are of type 16, and the rest are not of any recognized type, the following properties and counts are carried with the notification: numDeleted=20 numDeleted3=10 numDeleted16=7 |
|
numMsgs |
MQInt32 |
The total number of messages now in the mailbox. |
|
numMsgsnn |
MQInt32 |
The total number of messages now in the mailbox, specified for each message type. If message types are configured, a numMsgsnn property carries a count for each message type nn. The numMsgs property is always sent; it counts the total number of all messages in the mailbox, including all types. For example, if 20 messages are currently in the mailbox, 10 are of type 3, 7 are of type 16, and the rest are not of any recognized type, the following properties and counts are carried with the notification: numMsgs=20 numMsgs3=10 numMsgs16=7 |
|
numSeen |
MQInt32 |
The number of messages in the mailbox marked as seen (read). This number counts the messages read by the mailbox owner. If other users have access to the mailbox, their actions in the mailbox are not included in this count. (However, the other users' actions can trigger notifications such as ReadMsg). |
|
numSeennn |
MQInt32 |
The total number of messages in the mailbox marked as seen (read), specified for each message type. If message types are configured, a numSeennn property carries a count for each message type nn. The numSeen property is always sent; it counts the total number of all messages marked as seen, including all types. For example, if 20 messages are marked as seen, 10 are of type 3, 7 are of type 16, and the rest are not of any recognized type, the following properties and counts are carried with the notification: numSeen=20 numSeen3=10 numSeen16=7 |
|
numSeenDeleted |
MQInt32 |
The number of messages in the mailbox marked as seen (read) and marked as deleted. This number counts the messages marked as read and deleted by the mailbox owner. If other users have access to the mailbox, their actions in the mailbox are not included in this count. (However, the other users' actions can trigger notifications such as ReadMsgand DeleteMsg). |
|
numSeenDeletednn |
MQInt32 |
The total number of messages in the mailbox marked as seen (read) and marked as deleted, specified for each message type. If message types are configured, a numSeenDeletednn property carries a count for each message type nn. The numSeenDeleted property is always sent; it counts the total number of all messages marked as seen and deleted, including all types. For example, if 20 messages are marked as seen and deleted, 10 are of type 3, 7 are of type 16, and the rest are not of any recognized type, the following properties and counts are carried with the notification: numSeenDeleted=20 numSeenDeleted3=10 numSeenDeleted16=7 |
|
oldflags |
ConstMQString |
The flags set for the user's mailbox message before they were changed by the current operation. This property is always present, together with newflags, when a MsgFlags notification message is produced. For the syntax and values for oldflags, see Syntax for newflags and oldflags Properties, below this table. |
|
quotaRoot |
ConstMQString |
This can be a user name, folder name, or message type. |
|
size |
MQInt32 |
The size of the message. Note that this may not be the size of message body, since the body is typically a truncated version of the message. |
|
uidValidity |
MQInt32 |
The IMAP uid validity property. |
|
userid |
ConstMQString |
The userid associated with the message. |
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 (“ “).
22.3.5.3 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|
Property |
NewMsg, UpdateMsg |
ReadMsg, TrashMsg |
DeleteMsg, PurgeMsg |
MsgFlags
|
Login, Logout |
OverQuota, UnderQuota |
|---|---|---|---|---|---|---|
|
client |
No |
No |
No |
No |
Yes |
No |
|
diskquota |
No |
No |
No |
No |
No |
Yes |
|
diskquotaused |
No |
No |
No |
No |
No |
Yes |
|
hdrLen |
Yes |
No |
No |
Yes |
No |
No |
|
hostname |
Yes |
Yes |
Yes |
Yes |
Yes |
Yes |
|
imapUid |
Yes |
No |
Yes |
Yes |
No |
No |
|
lastUid |
No |
No |
Yes |
No |
No |
No |
|
mailboxName |
Yes |
Yes |
Yes |
Yes |
No |
No |
|
msgquota |
No |
No |
No |
No |
No |
Yes |
|
newflags |
No |
No |
No |
Yes |
No |
No |
|
numDeleted |
Yes |
Yes |
Yes |
No |
No |
No |
|
numDeletedn |
Yes* |
Yes* |
Yes* |
No |
No |
No |
|
numMsgs |
Yes |
Yes |
Yes |
No |
No |
Yes |
|
numMsgsn |
Yes* |
Yes* |
Yes* |
No |
No |
No |
|
numSeen |
Yes |
Yes |
Yes |
No |
No |
No |
|
numSeenn |
Yes* |
Yes* |
Yes* |
No |
No |
No |
|
numSeenDeleted |
Yes |
Yes |
Yes |
No |
No |
No |
|
numSeenDeletedn |
Yes* |
Yes* |
Yes* |
No |
No |
No |
|
oldflags |
No |
No |
No |
Yes |
No |
No |
|
Owner |
No |
Yes |
No |
No |
No |
No |
|
pid |
Yes |
Yes |
Yes |
Yes |
Yes |
Yes |
|
process |
Yes |
Yes |
Yes |
Yes |
Yes |
Yes |
|
quotaRoot |
No |
No |
No |
No |
No |
Yes |
|
size |
Yes |
No |
No |
No |
No |
No |
|
timestamp |
Yes |
Yes |
Yes |
Yes |
Yes |
Yes |
|
uidValidity |
Yes |
Yes |
Yes |
Yes |
No |
No |
|
userid |
No |
Yes |
No |
No |
Yes |
Yes |
Note –
* The numDeletedn, numMsgsn, numSeenn, and numSeenDeletedn properties are carried with notifications only if message types are defined in the message store.
- © 2010, Oracle Corporation and/or its affiliates