This chapter describes how to configure a JMQ notification plug-in to produce messages to be consumed by clients in a Message Queue service.
This chapter contains the following sections:Chapter 22, Configuring the JMQ Notification Plug-in to Produce Messages for Message Queue
The Messaging Server notification plug-in allows you to deliver notification messages to a messaging service or event service. The messaging service sends the notifications to consumers (client interfaces), which filter and deliver the messages to specified users.
For example, when new email arrives in a user's mailbox, the notification plug-in delivers a notification message to the messaging service. The message consumer, a component of the messaging service, receives the notification and sends it to the user's email client (such as Communications Express or Mozilla mail). The email client can then display a pop-up on the user's computer screen: “You have received a new message.”
Another example: if a user's mailbox exceeds its quota, the notification plug-in produces an over-quota notification message. The message consumer sends a warning to the user and to an administrator who needs to be informed of the event.
You can configure Messaging Server to deliver notifications to two different messaging services:
Sun Java System Message Queue 3.6 2005Q4
Event Notification Service
The Message Queue service implements the Java Messaging Service (JMS) specification, providing a message broker, interfaces to create clients that produce or consume messages, and administrative services and control. Message Queue follows the JMS standard for routing and delivery functions, protocols, and message formats.
The Event Notification Service is a component bundled with Messaging Server and Sun Java System Calendar Server. It is a proprietary service that uses a publish/subscribe architecture for sending and receiving event notifications.
You can configure a notification producer for Message Queue, for the Event Notification Service, or for both services.
This chapter describes how to configure notifications for Message Queue only.
For information about the Event Notification Service, see the Sun Java System Communications Suite Event Notification Service Guide.
To enable Messaging Server to produce notifications to Message Queue or the Event Notification Service, you must configure a plug-in for that service:
The JMQ notification plug-in allows you to deliver notification messages to the Message Queue broker.
The iBiff plug-in allows you to publish notification events to the Event Notification Service.
For information on how to load the iBiff plug-in and configure the Event Notification Service, see “Appendix B: Administering Event Notification Service in Messaging Server,” in the Sun Java System Messaging Server Administration Guide.
The JMQ notification plug-in, with Message Queue, provides the following benefits:
Message Queue implements the JMS standard.
With Message Queue, you can produce messages to a topic or a queue, or to both of these delivery methods. For a brief definition, see 22.1.3.1 Publishing to a Topic or a Queue.
Message Queue offers enhanced load balancing during message distribution, especially when messages are produced to a queue.
The JMQ notification plug-in allows you to configure up to five notification plug-ins. The different plug-ins can produce messages to a topic, to a queue, to the Event Notification Service, and so on. For details, see 22.1.3.2 Using Multiple JMQ Notification Plug-ins.
Message Queue provides reliable delivery of notifications.
For example, if you configure the JMQ notification plug-in to produce messages with the persistent flag enabled, the message remains in the Message Queue broker until a consumer receives it. The message is saved so that, if a server goes down, the message can be retrieved and made available to the appropriate consumer.
A topic and queue use different messaging delivery patterns; each one can be configured in a Message Queue service.
Topic. When a message producer sends a message to a topic, a publish/subscribe architecture is used. In this broadcast pattern, a producer sends a message to a topic destination. Any number of consumers can be subscribed to this topic destination. Each consumer subscribed to the topic gets its own copy of the message. If no consumers are subscribed to the topic, the message is discarded.
The Event Notification Service also uses a publish/subscribe architecture; it is similar to the topic pattern defined in Message Queue.
Queue. When a message producer sends a message to a queue, a point-to-point architecture is used. In this pattern, a producer sends a message to a queue destination from which only one consumer can receive it. If several consumers are waiting for messages from the queue, only one subscriber will receive the message. If no consumers are waiting, the message is held until either the message times out, or a consumer expresses an interest in the queue.
Producing messages to a queue allows you to spread the message load across multiple consumers.
You can configure from one to five notification plug-ins.
Messaging Server provides a plug-in library at the following default location:
/opt/SUNWmsgsr/lib/libjmqnotify
You use the configutil utility to specify parameters for a plug-in and to point the plug-in to the library of executable code.
If you specify more than one plug-in, each plug-in produces notification messages independently of the others. For example, if two plug-ins are configured with a delete-message parameter, and a message is deleted from a user's mailbox, both plug-ins will produce a notification message.
By configuring multiple plug-ins, you can take advantage of different message-distribution patterns for different purposes. For example, you could configure three different plug-ins to produce messages
To a queue (using Message Queue)
To a topic (using Message Queue)
To the Event Notification Service
For each plug-in you configure, you must define a separate set of configutil parameters.
The parameters determine two kinds of information:
The kinds of notification messages to produce. For example, enabling the LogUser parameter causes a notification message to be sent whenever a user logs in or out.
Configuration information needed by Message Queue. For example, the jmqHost parameter identifies the IP address of the host where the Message Queue broker is running.
For instructions on how to configure a plug-in, see To Configure a JMQ Notification Plug-in.
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.
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.
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.
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
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.
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:
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".
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.
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).
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.* |
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.* |
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.
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.
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.
You can configure a notification message to be sent when an email message has changed status.
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.
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.
You must configure both parameters to enable notifications for message flags.
Enable status flags to be tracked and status information to be carried with message-flag notifications:
configutil -o local.store.notifyplugin.MsgFlags -v 1 |
where -v 1 enables message-flag information to be sent with message-flag notifications. A value of 0 disables this notification.
Enable message-flag notifications to be sent by a particular plug-in:
configutil -o local.store.notifyplugin.jmqnotify.MsgFlags.enable -v 1 |
where jmqnotify is the name of the plug-in
and -v 1 enables message-flag notifications for this plug-in. A value of 0 disables notifications.
This section describes the following topics:
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. |
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 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.
The Event Notification Service does not support message types. Use a JMQ notification plug-in to deliver information about message types.
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 |
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.
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). |
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. |
Subscribers should allow for undocumented properties when parsing the message reference. This allows for future compatibility when new properties are added.
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 (“ “).
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 |
* The numDeletedn, numMsgsn, numSeenn, and numSeenDeletedn properties are carried with notifications only if message types are defined in the message store.