Changes between Initial Version and Version 1 of TracDev/Proposals/AdvancedNotification/INotificationDistributor

Timestamp:

Nov 17, 2012, 10:38:38 PM (11 years ago)

Author:

Peter Suter

Comment:

Document the proposed INotificationDistributor extension point.

TracDev/Proposals/AdvancedNotification/INotificationDistributor

@@ +1 @@
+== Extension Point : ''INotificationDistributor'' ==
+
+||'''Interface'''||''INotificationDistributor''||'''Since'''||[wiki:TracDev/ApiChanges/1.1.1#INotificationDistributor 1.1.1]||
+||'''Module'''||''trac.notification''||'''Source'''||[source:trunk/trac/notification/api.py#/INotificationDistributor api.py]||
+
+
+The ''INotificationDistributor'' sends [TracNotification notification] events over some distribution channel, like email.
+
+== Purpose ==
+
+Trac provides an extendible and flexible notification system, that historically has sent notifications by email. Notifications could however also be distributed by XMPP, SMS or any other messaging protocol.
+
+== Usage ==
+
+Implementing the interface follows the standard guidelines found in [wiki:TracDev/ComponentArchitecture] and of course [wiki:TracDev/PluginDevelopment].
+
+A simple `transports()` method lists the names of the supported transports (protocols / distribution channels). The `distribute()` method distributes a message to one or more recipients. It receives the following parameters:
+* `transport`: The name of the transports that should be used. One of those returned by `transports()`.
+* `recipients`: A list of `(sid, authenticated, address, format)` tuples. 
+  * `sid`: The Trac session ID of the recipient (or `None`).
+  * `authenticated`: `1` if the Trac session ID is authenticated, `0` otherwise.
+  * `address`: A protocol specific address to send the notification to. If it is `None` the implementation might still be able to send the message to the recipient using the `sid` / `authenticated` information somehow. (E.g. the `EmailDistributor` falls back to [wiki:IEmailAddressResolver IEmailAddressResolver] implementations.)
+  * `format`: MIME type of the message format to be used. 
+* `event`: A `trac.notification.api.NotificationEvent` instance describing the event about which the recipients should be notified.
+
+The `event` is supposed to be formatted into a message in the given `format` using a [wiki:INotificationFormatter INotificationFormatter].
+
+== Examples ==
+
+The following example distributes notifications by SMS. (The `sms` library does not exist. Several commercial SMS services provide real APIs.)
+
+{{{#!python
+from itertools import groupby
+from operator import itemgetter
+
+from trac.core import *
+from trac.notification.api import INotificationDistributor, \
+                                  INotificationFormatter
+
+import sms
+
+class SmsNotificationDistributor(Component):
+
+    implements(INotificationDistributor)
+
+    formatters = ExtensionPoint(INotificationFormatter)
+
+    # INotificationDistributor methods
+
+    def transports(self):
+        return ['sms']
+
+    def distribute(self, transport, recipients, event):
+        if transport != 'sms':
+            return
+
+        # Group by message format:
+        for format, group in groupby(recipients, itemgetter(3)):
+            formatter = None
+            for f in self.formatters:
+                for style in f.styles(transport, event.realm):
+                    if style == format:
+                        formatter = f
+            if formatter:
+                message = formatter.format(transport, format, event)
+                for sid, authenticated, address, format in group:
+                    if address:                        
+                        sms.send(message, address)
+}}}
+
+== Available Implementations ==
+
+Only `trac.notification.mail.EmailDistributor` is part of core Trac.
+
+`XmppDistributor` will be part of th:AnnouncerPlugin.
+
+== Additional Information and References ==
+
+ * [http://www.edgewall.org/docs/trac-trunk/epydoc/trac.notification.api.INotificationDistributor-class.html epydoc]
+ * [http://www.edgewall.org/docs/trac-trunk/html/api/trac_notification.html#trac.notification.api.INotificationDistributor API Reference]
+ * Related to the [wiki:INotificationFormatter INotificationFormatter]
+ * This interface originated in th:AnnouncerPlugin as `IAnnouncementDistributor`.