Gallery2:Design Documents:NotificationIntegration

Notification Integration

The purpose of this page is to provide a discussion of how to integrate the Notification module into trunk.

Gallery2 currently has a comprehensive event notification mechanism. Modules that wish to be notified of events, register an 'EventListener' that will be called when that event is posted. The current notification module duplicates this functionality and creates a similar event mechanism. Although this was the right approach when created as a non-trunk module, it introduces duplication and inflexibility when integrated into trunk. If a new event notification is required, then changes to the module that causes this event to occur would be required, even if this module is already posting an event to the existing system.

The premise of this design is to leverage the existing event system instead of integrating a second parallel notification system and create an extensible framework that allows future modules to extend the framework, by providing additional notification handlers. The under lying philosphy is that any event should be a source for some kind of notification.

Core Enhancements

To this end, I envision the following changes to the core module:

1. In order for an event to show in the Site Notification Administration, the implementing module must register a notification event as a NotificationEvent factory implementation class type. The name of the notification event should be the same as the event id (i.e. Gallery::ActivatePlugin).
2. Modules must register any notification handlers they implement as a NotificationHandler factory implementation class type.
3. ItemAdd.inc will be changed to fire a new event (Gallery::ItemAdded) when an batch of items has been added. The intent is to only fire one event for each batch of items that has been added. This approach replaces the NotificationItemOption that was defined in the current version of the Notification module.
4. GalleryCoreApi will be changed to expose two new methods getFactoryDefinitionHints and updateFactoryDefinitionHints to allow the Notification module to dynamically subscribe or unsubscribe to Gallery 2 events.

   Modules that listen for Gallery events, register a factory implementation class of GalleryEventListener and as part of the registration process, supply an array of hints. In the case of GalleryEventListener implementations, these hints are are the names of the events that the listener is willing to accept. This registration is typically done once during module activation. Unregistering the listeners happens as part of the module deactivation.

   In the case of the notification module, the events that notification listener wants to listen to are not known, as these will be defined later by the administrator and eventually users subscribing to published events. It is inefficient and inflexible to add the notification listener for all the events, so some mechanism is required to dynamically update the hints field without having to unregister and re-register the notification listener.

   • Given the factory implementation class and the implementation id, getFactoryDefinitionHints returns the associated hints.
   • updateFactoryDefinitionHints is the reciprocal function, it will replace the existing hints for the factory implementation class/implementation id combination with the suppliedhints.

   When a event name is removed from the hint list, the listener is then ignored by the eventing posting algorithm. These methods give the ability to register an event listener at module activation but allow it's participation in the event processing to be dynamically enabled or disabled.

Notification Module Changes

The current notification module would be changed as follows:

1. The NotificationEvent class will provide the notification information that can be used by the event notification handlers. The following methods will be defined:
   • getDescription: An abstract method to return a description of the event. This will show up in the Description field of the Site Notification Administration and other event notification screen.
   • getNotifyMessage: An abstract method to return the text message that will be included in any notification emails. Rather than trying to create a generalized message formatter, each Event is responsible for formating the message to be displayed.
   • getPermission: An abstract method that returns the users required permissions in order to send notification.
2. The interface NotificationEventInterface_1_0 will be modified to extend GalleryEventListener. In addition to the handleEvent method of GalleryEventListener class the the following methods will be defined:
   • getDescription: An abstract method to return a description of the handler. This will show up in the Description field of the Site Notification Administration and other event notification screen.
   • getName: An abstract method to return the name of the notification handler.
3. A notification administration screen is added that allows the administrator to create a mapping between an event and a notification handler. In addition the screen would allow the administrator to determine which of the event/notification handler pairs would be available for the end user to subscribe to.
4. The watch and user administration screens would be only available if there were any event/notification handler pairs that were exposed to the end user. At this point, I don't envision any changes to the user administration or add Watch to item screens.
5. The NotificationEvent and NotificationMethod maps will be removed as this information is now stored in the FactoryMap.
6. Rather than creating a new database table to maintain the enabled/disabled information, it will be serialized to a single plug-in parameter. In addition, this array will store which of the event/handler pairs end users can subscribe to.

In addition, the following classes will no longer be defined in the Notification Module:

• NotificationEventItemAdd: Moved to core.
• NotificationMethodInterface_1_0: removed
• NotificationSystemInterface_1_0: removed
• NotificationSystem.class: removed.

Site Administration

A notification administration screen would be provided that performed two functions. The first is to match up registered events with registered handlers. The second function would be to determine which of the events/handler combinations would available for the end users to subscribe to. If the event/handler is not public, then the administrator id will be subscribed to that event.

In the above example, the Comment Added Event is connected to the Send an email handler and is made public. The User Login Failed event will send an email to the administrator.

Event Processing

When the Site Notification Administration the events that have a Notification Handler associated with them will be registered as event listeners for that event. On the event fires then the Notification Handler will be called directly. If the administrator has not associated a notification handler with an event, then the event would not be registered.

Permissions

The following algorithm will be used to determine permissions:

• if there's an itemId in the event-data, use it.
• if not, check if the event has an entity and if the entity is an item. if so, use that itemId.
• if we don't have an itemId, check the notification event permission to see if the user has that permission.