Sun Java System Messaging Server 6.3 管理指南

22.3 JMQ 通知邮件和属性

本节介绍了以下主题：

22.3.1 通知邮件

可以为消息存储中发生的各种事件生成通知邮件。例如，用户登录时，可以生成 Login 邮件并发送到 Message Queue 代理。

configutil 参数指定每种生成的邮件。通过配置各种 configutil 参数，您可以决定哪些事件会生成邮件。configutil 参数可以被一个或多个 JMQ 通知插件库引用。

所有邮件都被传送到主题或队列，具体取决于将目标类型设置为 "topic" 还是 "queue"。有关如何配置 Message Queue 目标的信息，请参见配置 JMQ 通知插件。

每个邮件由以下邮件标题标识：

MQ_MESSAGE_TYPE_HEADER_PROPERTY

JMQ 通知插件支持的邮件如下表所示。

有关启用这些邮件的 configutil 参数列表，请参见22.3.4 configutil 参数的默认值。

表 22–1 JMQ 通知邮件


通知邮件	说明
`DeleteMsg`	从邮箱中删除标记为“已删除”的邮件。此操作等效于 IMAP 擦除。
`Login`	用户从 IMAP、HTTP 或 POP 登录。（用 `configutil` 参数 `local.store.notifyplugin.*.LogUser.enable` 启用此邮件。）
`Logout`	用户从 IMAP、HTTP 或 POP 注销。（用 `configutil` 参数 `local.store.notifyplugin.*.LogUser.enable` 启用此邮件。）
`MsgFlags`	邮件上的邮件标志已更改。新旧标志会包含在此邮件中。
`NewMsg`	系统收到新邮件并放入用户邮箱中。可以包含邮件标题和邮件正文。
`OverQuota`	由于用户邮箱超过某个配额（diskquota 或 msgquota）导致操作失败。MTA 通道会保留邮件直到配额更改或用户邮箱计数低于配额。如果邮件在 MTA 保留期间过期，将清除该邮件。
`PurgeMsg`	邮件被服务器进程 imexpire 从邮箱中清除（由于日期过期）。这是服务器端的清除，而 DeleteMsg 是客户端的清除。这并不是真正意义上的清除。
`ReadMsg`	邮箱中的邮件已阅读。（在 IMAP 协议中，邮件标记为 Seen。）
`TrashMsg`	被标记的邮件将被 IMAP 或 HTTP 删除。用户可能仍然会在文件夹中看到此邮件，具体取决于邮件客户端的配置。在执行清除时，邮件将从文件夹中删除。
`UnderQuota`	配额从 OverQuota 状态恢复到正常状态。
`UpdateMsg`	通过 IMAP 操作，将邮件附加到邮箱。例如，用户将一个电子邮件复制到邮箱。可以包含邮件标题和邮件正文。

22.3.2 通知邮件的规则和原则

以下规则和原则应用于支持的通知邮件：

大部分通知邮件的文本都是一个空白区。（使用空白区是因为 Message Queue 不允许邮件正文为空。）例外情况如下：
- 在使用 maxHeaderSize 参数配置时，NewMsg、UpdateMsg 和 DeleteMsg 邮件可以包含邮件标题。您必须将 maxHeaderSize 设置为大于 0 的值。
  
  要使 DeleteMsg 邮件包含邮件标题，还必须将 ExpungeHeaders 参数的值设置为 1。
- 在使用 maxBodySize 参数配置时，NewMsg 和 UpdateMsg 邮件可以包含邮件正文。您必须将 maxBodySize 设置为大于 0 的值。
  
  对于 NewMsg 和 UpdateMsg 而言，默认情况下不传送（关闭）邮件正文。这可以防止 Message Queue 过载。其他邮件都不包含邮件正文。
可以只为 INBOX 的更改生成通知邮件，也可以为 INBOX 和所有其他文件夹的更改生成通知邮件。以下配置参数允许只为 INBOX 生成（值 = 0），或为 INBOX 和所有其他文件夹生成（值 = 1）：
```
local.store.notifyplugin.jmqnotify.noneInbox.enable
```
默认设置是只从 INBOX 生成邮件（值 = 0）。

没有选择文件夹的机制；当此变量启用时包含所有文件夹（值 = 1）。
只有在邮件被置于用户邮箱后（而非“服务器接受它并将其放入邮件队列后”）才发出 NewMsg 通知。
不为 POP3 客户端访问生成邮件。
可以通过发出 XNOTNOTIFY 抑制所有邮件。例如，仅用于内务处理的 IMAP 脚本（不打算通知用户）可能会发出 XNOTNOTIFY 抑制所有邮件。

22.3.3 特定邮件类型的通知

通知可以传送关于各种不同类型的邮件（例如文本邮件、语音邮件和图像数据）的状态信息。用户经常希望这些不同种类的邮件类型存储在同一个邮件文件夹内。例如，用户可能希望新文本邮件和语音邮件都到达用户的手机收件箱。

要配置这些邮件类型，请使用 configutil 命令，例如 store.messagetype.enable。有关配置和管理邮件类型的信息，请参见“第 18 章：管理消息存储”中的“管理邮件类型”。

一旦配置了邮件类型，JMQ 通知邮件就能够标识特定邮件类型。您可以编写 Message Queue 客户端，使其能够按邮件类型解释通知邮件并向邮件客户端传送关于每个类型的状态信息。

例如，假设不同类型的新邮件到达用户的邮箱。NewMsg 通知邮件可以包含要通知用户的数据（例如，用户收件箱中有七个新语音邮件和四个新文本邮件）。

以下通知邮件可以包含跟踪特定邮件类型的信息：

NewMsg
UpdateMsg
ReadMsg
TrashMsg
DeleteMsg
PurgeMsg
OverQuota
UnderQuota

JMQ 通知功能可以按邮件类型统计邮箱中的当前邮件数。随通知邮件发送的是指定每种邮件类型计数的数组，而不是一个计数。

特定于邮件的计数包含在 numMsgs 属性中并随通知邮件一起传送。对于 ReadMsg 和 TrashMsg 通知邮件，已读邮件的数量 (numSeen) 和标记为已删除的邮件数量 (numDeleted) 也按邮件类型计数。

注 –

Event Notification Service 不支持邮件类型。使用 JMQ 通知插件传送关于邮件类型的信息。

22.3.4 `configutil` 参数的默认值

用 configutil 参数配置 Message Queue 需要的通知邮件和配置信息。

表 22–2 显示了这些参数及其默认值。

有关 configutil 参数的完整定义，请参见 Sun Java System Messaging Server Administration Reference 中的第 3 章 "Messaging Server Configuration"。

表 22–2 configutil 参数及其默认值


`configutil` 参数	默认值
`local.store.notifyplugin.*.maxBodySize`	0 — 禁用
`local.store.notifyplugin.*.maxHeaderSize`	0 — 禁用
`local.store.notifyplugin.*.NewMsg.enable`	1 — 启用
`local.store.notifyplugin.*.UpdateMsg.enable`	1 — 启用
`local.store.notifyplugin.*.ReadMsg.enable`	1 — 启用
`local.store.notifyplugin.*.DeleteMsg.enable`	1 — 启用
`local.store.notifyplugin.*.PurgeMsg.enable`	1 — 启用
`local.store.notifyplugin.*.LogUser.enable`	1 — 启用
`local.store.notifyplugin.*.MsgFlags.enable`	0 — 禁用
`local.store.notifyplugin.*.noneInBox.enable`	0 — 禁用
`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 — 表示此邮件永不超时。
`local.store.notifyplugin.*.Persistent`	1 — 启用

22.3.5 通知邮件属性

每个邮件都包含属性中定义的附加信息。不同的属性出现在不同的邮件中。例如，NewMsg 表示新邮件的 IMAP uid。

22.3.5.1 标准通知邮件属性

表 22–3 介绍了标准通知邮件属性。这些属性出现在所有 JMS 邮件中。

表 22–3 标准通知邮件属性


属性	数据类型	说明
`hostname`	ConstMQString	生成此邮件的计算机的主机名。
`pid`	MQInt32	生成此邮件的进程的 ID。
`process`	ConstMQString	指定生成此邮件的进程的名称。
`timestamp`	MQFloat64	指定从 epoch（GMT 时间 1970 年 1 月 1 日午夜）开始的毫秒数。

22.3.5.2 特定于特定通知邮件的属性

表 22–4 描述了特定通知邮件包含的属性。

每个邮件包含下表中属性的一个子集。有关与每个邮件相关的属性列表，请参见表 22–5。

表 22–4 特定于特定通知邮件的属性


属性	数据类型	说明
`client`	ConstMQString	与邮件相关的 Message Queue 客户端 IP 地址。
`diskquota`	MQInt32	与邮件相关的用户磁盘空间配额，以千字节为单位。值设置为 -1 表示没有配额。
`diskquotaused`	MQInt32	与邮件相关的用户磁盘空间使用量，以千字节为单位。
`hdrLen`	MQInt32	邮件标题大小。请注意，这可能不是邮件正文中标题的大小，因为此标题可能已经被截断。
`imapUid`	MQInt32	与邮件相关的 IMAP uid 属性。
`lastUid`	MQInt32	邮箱中使用的最后一个 IMAP uid 值。
`mailboxName`	ConstMQstring	与事件相关的消息存储邮箱名称。mailboxName 可以使用以下几种格式之一（其中 `uid` 是用户的唯一标识符）： `uid` — 标识默认（主）域中用户的收件箱。 `uid@domain` — 标识托管域中用户的收件箱。 `uid/mailboxname` — 标识默认域中用户的顶层邮箱。 `uid@domain/mailboxname` — 标识托管域中用户的顶层邮箱。 `uid/foldername/mailboxname` — 标识默认域中用户文件夹中的邮箱。 `uid@domain/foldername/mailboxname` — 标识托管域中用户文件夹中的邮箱。
`msgquota`	MQInt32	用户的最大邮件数配额。值设置为 -1 表示没有配额。
`newflags`	ConstMQString	用户的邮箱邮件被当前操作改变后设置的标志。在生成 `MsgFlags` 通知邮件时，此属性总是与 `oldflags` 一起出现。有关 `newflags` 的语法和值，请参见此表下面的newflags 和 oldflags 属性的语法。
`numDeleted`	MQInt32	邮箱中标记为已删除的邮件数量。此数值统计被邮箱所有者删除的邮件。如果其他用户访问此邮箱，他们在邮箱中的操作不包括在此计数内。（但是，其他用户的操作能够触发通知，如 `DeleteMsg` ）。
`numDeleted`nn	MQInt32	邮箱中为每种邮件类型指定的标记为已删除的邮件总数。如果配置了邮件类型， `numDeleted`nn 属性将包含每种邮件类型 nn 的计数。始终发送 `numDeleted` 属性；它统计所有标记为已删除的邮件的总数，包括所有类型。例如，如果 20 个邮件被标记为已删除，其中 10 个是类型 3，7 个是类型 16，而其余的不属于任何已识别的类型，则通知中包含以下属性和计数： `numDeleted=20` `numDeleted3=10` `numDeleted16=7`
`numMsgs`	MQInt32	邮箱中当前邮件总数。
`numMsgs`nn	MQInt32	邮箱中为每种邮件类型指定的当前邮件总数。如果配置了邮件类型， `numMsgs`nn 属性将包含每种邮件类型 nn 的计数。始终发送 `numMsgs` 属性，它统计邮箱中所有邮件的总数，包括所有类型。例如，如果邮箱中当前有 20 个邮件，其中 10 个是类型 3，7 个是类型 16，而其余的不属于任何已识别类型，则通知中包含以下属性和计数： `numMsgs=20` `numMsgs3=10` `numMsgs16=7`
`numSeen`	MQInt32	邮箱中标记为已读（已阅读）的邮件数。此数值统计已被邮箱所有者阅读的邮件。如果其他用户访问此邮箱，他们在邮箱中的操作不包括在此计数内。（但是，其他用户的操作能够触发通知，如 `ReadMsg`）。
`numSeen`nn	MQInt32	邮箱中为每种邮件类型指定的标记为已读（已阅读）的邮件总数。如果配置了邮件类型，`numSeen` nn 属性将包含每种邮件类型 nn 的计数。始终发送 `numSeen` 属性；它统计邮箱中所有标记为已读的邮件的总数，包括所有类型。例如，如果邮箱中有 20 个标记为已读的邮件，其中 10 个是类型 3，7 个是类型 16，而其余的不属于任何已识别类型，则通知中包含以下属性和计数： `numSeen=20` `numSeen3=10` `numSeen16=7`
`numSeenDeleted`	MQInt32	邮箱中标记为已读（已阅读）和已删除的邮件数。此数值统计已被邮箱所有者标记为已阅读和已删除的邮件。如果其他用户访问此邮箱，他们在邮箱中的操作不包括在此计数内。（但是，其他用户的操作能够触发通知，如 `ReadMsg` 和 `DeleteMsg`）。
`numSeenDeleted`nn	MQInt32	邮箱中为每种邮件类型指定的标记为已读（已阅读）和已删除的邮件总数。如果配置了邮件类型，`numSeenDeleted`nn 属性将包含每种邮件类型 nn 的计数。始终发送 `numSeenDeleted` 属性；它统计邮箱中所有标记为已读和已删除的邮件的总数，包括所有类型。例如，如果邮箱中有 20 个标记为已读和已删除的邮件，其中 10 个是类型 3，7 个是类型 16，而其余的不属于任何已识别类型，则通知中包含以下属性和计数： `numSeenDeleted=20` `numSeenDeleted3=10` `numSeenDeleted16=7`
`oldflags`	ConstMQString	用户的邮箱邮件被当前操作改变前设置的标志。在生成 `MsgFlags` 通知邮件时，此属性总是与 `newflags` 一起出现。有关 `oldflags` 的语法和值，请参见此表下面的newflags 和 oldflags 属性的语法。
`quotaRoot`	ConstMQString	此属性可以是用户名、文件名或邮件类型。
`size`	MQInt32	邮件大小。请注意，此属性可能不是邮件正文的大小，因为正文通常是邮件被截断的版本。
`uidValidity`	MQInt32	IMAP uid 有效性属性。
`userid`	ConstMQString	与邮件相关的 userid。

注 –

在解析邮件引用时，订户应该允许没有记录的属性。这考虑未来添加新属性时的兼容性。

newflags 和 oldflags 属性的语法

newflags 和 oldflags 属性是 5–字符字符串。此字符串必须有以下值：

如果设置了 /answered 标志，则第一个字符为 "A"。否则，为空白 (" ")。
如果设置了 /flagged 标志，则第二个字符为 "F"。否则，为空白 (" ")。
如果设置了 /deleted 标志，则第三个字符为 "D"。否则，为空白 (" ")。
如果设置了 /seen 标志，则第四个字符为 "S"。否则，为空白 (" ")。
如果设置了 /draft 标志，则第五个字符为 "R"。否则，为空白 (" ")。

22.3.5.3 每个通知邮件包含的属性

表 22–5 显示了与每个通知邮件相关的属性。

例如，要查看哪些属性可以应用于 TrashMsg 邮件，请在列标题中查找 "ReadMsg, TrashMsg"。除了标准属性之外，TrashMsg 邮件还可以使用 mailboxName、 numMsgs、uidValidity、numSeen 和 numDeleted。

表 22–5 每个通知邮件包含的属性


属性	NewMsg, UpdateMsg	ReadMsg, TrashMsg	DeleteMsg, PurgeMsg	MsgFlags	Login, Logout	OverQuota, UnderQuota
`client`	否	否	否	否	是	否
`diskquota`	否	否	否	否	否	是
`diskquotaused`	否	否	否	否	否	是
`hdrLen`	是	否	否	是	否	否
`hostname`	是	是	是	是	是	是
`imapUid`	是	否	是	是	否	否
`lastUid`	否	否	是	否	否	否
`mailboxName`	是	是	是	是	否	否
`msgquota`	否	否	否	否	否	是
`newflags`	否	否	否	是	否	否
`numDeleted`	是	是	是	否	否	否
`numDeleted`n	是*	是*	是*	否	否	否
`numMsgs`	是	是	是	否	否	是
`numMsgs`n	是*	是*	是*	否	否	否
`numSeen`	是	是	是	否	否	否
`numSeen`n	是*	是*	是*	否	否	否
`numSeenDeleted`	是	是	是	否	否	否
`numSeenDeleted`n	是*	是*	是*	否	否	否
`oldflags`	否	否	否	是	否	否
`Owner`	否	是	否	否	否	否
`pid`	是	是	是	是	是	是
`process`	是	是	是	是	是	是
`quotaRoot`	否	否	否	否	否	是
`size`	是	否	否	否	否	否
`timestamp`	是	是	是	是	是	是
`uidValidity`	是	是	是	是	否	否
`userid`	否	是	否	否	是	是

注 –

* 只有在消息存储中定义了邮件类型，通知才会包含 numDeletedn、numMsgs n、numSeenn 和 numSeenDeletedn 属性。

22.3 JMQ 通知邮件和属性

22.3.1 通知邮件

22.3.2 通知邮件的规则和原则

22.3.3 特定邮件类型的通知

22.3.4 configutil 参数的默认值

22.3.5 通知邮件属性

22.3.5.1 标准通知邮件属性

22.3.5.2 特定于特定通知邮件的属性

newflags 和 oldflags 属性的语法

22.3.5.3 每个通知邮件包含的属性

22.3.4 `configutil` 参数的默认值