Notifications Filters API
Handle the filters that can be applied on notifications |
Type | JAR |
Category | API |
Developed by | |
Rating | |
License | GNU Lesser General Public License 2.1 |
Bundled With | XWiki Standard |
Table of contents
Description
Concepts
By default, when a user selects an event type to survey, she receives notifications for all events of that event type (except the ones that are anterior to a date configured by that user).
That might be too much. That is why we have introduced the Notification Filters. A notification filter introduce restrictions for an event type. For example, it will restricts "update" events on the page Movies and this children, meaning that all events that do not concern pages contained under Movies will not be seen as notification.
But you could image other filters: display only notifications about events sent by a particular user, or about pages containing a specific keyword... It's up to you (and the developers who work for you)!
You can also create filters that are not bound to any event type. We call them global filters internally. They can implement the same restrictions, except that they will concern all events.
Inclusive and Exclusive notification filters
Your can also design you filter not to restrict the events given by the Notification Manager on some conditions (we call that kind of filters exclusive filters), but to add other events to that list. We call them inclusive filters. They are not "filters" strictly speaking, but we implement them with the same component role.
Notification Filter Preferences
A Notification Filter provides a generic mechanism to filter on events according to some rules. For example, the ScopeNotificationFilter implements the algorithm to restrict the notifications of any set of locations. But if you want to select the location on which you want to restrict, you need to tell it to the ScopeNotificationFilter with a NotificationFilterPreferences.
A NotificationFilterPreferences is a generic object that can contain some properties, such as: APPLICATION, PAGE, USER, etc... the complete list is here. Each NotificationFilterPreferences specifies which filter it concerns thanks to the method getFilterName(). For example, if the filter preference concerns the ScopeNotificationFilter, getFilterName() will return scopeNotificationFilter, which is the filter hint. The way the preference is used by the Notification Filter is up to that filter. There is no imposed behavior.
You can even decide not to use the Notification Filter Preferences mechanism and implement your own way of giving more information to your Notification Filter.
Abstract Syntax Tree (AST)
We have introduced an Abstract Syntax Tree (AST) to generate the query that fetch the events we want to display as notifications.
This AST has been created for 2 reasons:
- in the future, the events might be stored in a different way, and the current HQL query might be not effective on a different storage (such as NoSQL). This AST abstracts the language so the query could still be effective, as soon as we have a translator for the target language.
- it's easier for developers to write a NotificationFilter by generating an AST than generating a good HQL query that must escape its values and co-exists with other filters...
See the current list of available expression nodes.
Since theses nodes have been created for our own implementation needs, please open a JIRA issue if you wish to have more.
How to create my own Notification Filter?
What you need to do is to create your own implementation of https://github.com/xwiki/xwiki-platform/blob/master/xwiki-platform-core/xwiki-platform-notifications/xwiki-platform-notifications-filters/xwiki-platform-notifications-filters-api/src/main/java/org/xwiki/notifications/filters/NotificationFilter.java##.
There is 2 main methods to implement:
- filterExpression(): generate an AST to customize the query that will look for events to display as notifications
- filterEvent(): after the query is executed, return if the given event should be displayed or not according to criteria that was not possible to implement in the AST. It is also used on the Live Notification Email mode, so it needs to do at least what filterExpression() does.
Prerequisites & Installation Instructions
We recommend using the Extension Manager to install this extension (Make sure that the text "Installable with the Extension Manager" is displayed at the top right location on this page to know if this extension can be installed with the Extension Manager).
You can also use the manual method which involves dropping the JAR file and all its dependencies into the WEB-INF/lib folder and restarting XWiki.
Dependencies
Dependencies for this extension (org.xwiki.platform:xwiki-platform-notifications-filters-api 16.9.0):
- org.xwiki.platform:xwiki-platform-notifications-api 16.9.0
- org.xwiki.platform:xwiki-platform-component-wiki 16.9.0
- org.xwiki.platform:xwiki-platform-model-api 16.9.0
- org.xwiki.platform:xwiki-platform-wiki-api 16.9.0
- org.xwiki.platform:xwiki-platform-notifications-preferences-api 16.9.0