Grails Notifications Plugins

  • Authors: Bruno Félix, Nuno Lopes Luis
0 vote
Dependency:
compile ":notifications:0.2.6"

 Documentation  Source  Issues

Summary

The notifications plugin is a generic plugin that implements a publish-subscribe model to push information to subscribers through different communication channels.

Installation

Installation:

grails install-plugin notifications

Description

Description:

The notifications plugin is a generic plugin that implements a publish-subscribe model to push information to subscribers through different communication channels. Notifications may also be scheduled to be sent at a later date.

Note: As of version 0.2.4 users can define their own classes for the subscribers and subscriptions - In the spirit of what is done with the user classes in spring security core.

Key concepts:

  • Notification: The the message that needs to be passed on to subscribers. Each notification has a topic (which can have subscriptions), and a message. Optionally it may also have a scheduled date, useful for sending notifications at a later date.
  • Subscription: Relates subscribers to topics and can have several communication channels associated. That is, when a topic is subscribed, the user also chooses the channels through which he wants to be notified.
  • Channel: It is an abstraction of a messaging channel, holding information about the class that implements the communication protocol. Each subscriber can have several of these channels, that control how he receives the subscriptions.

Initialization:

After the plugin is installed, run the notificationSetup script, to setup the classes for the subscriber and subscription.

Usage: grails notificationSetup <domain-class-package> <subscriber-class-name> <subscription-class-name>

Example: grails notificationSetup com.myapp MySubscriber MySubscription

Once the script has finished, the plugin is ready to be used.

If you wish you can manually implement these classes. The plugin expects each subscriber to have many subscriptions, many channels and an alias. A subscription should belong to a subscriber, and have a notification topic and many channels. For further details on these fields check the code under /src/templates.

The Config.groovy file is also updated by the script, adding three new entries, that should be self-explanatory: 1 - grails.plugins.notifications.domainClassPackage 2 - grails.plugins.notifications.subscriberDomainClass 3 - grails.plugins.notifications.subscriptionDomainClass

Sample usage:

In terms of usage this plugin exposes a service, conveniently called "NotificationService", that allows subscription, scheduling and sending of notifications. For the purposes of this document we assume that com.myapp.MySubscriber and com.myApp.MySubscription are the classes that have been generated using the notificationSetup script.

Usually the first step is subscribing a topic:

def notificationService

(...)

def subscriberId= 42 def defaultTopic = "Some topic" def channels = [ new Channel(channelImpl: ChannelType.Email.implementingClass, destination: "test.user@acme.com") ]

//Create a new subscriber, and add some channels through which he wants to recieve notifications def subscriber = com.myapp.MySubscriber.get(subscriberId)

//Subscribe using all available channels for that subscriber def subscription = notificationService.subscribeTopic(subscriber, defaultTopic, subscriber.channels.first())

To send a notification, the service has a sendNotification method that has the following arguments:

  • topic
  • message
  • scheduledDate (optional)
In the example below a notification is sent immediately.

def notificationService

(...) def defaultTopic = "Some topic" def topic = NotificationTopic.findByTopic(defaultTopic)

def notification = new Notification(message: "PUB/SUB notification", topic: topic).save()

notificationService.sendNotification(notification)

Notifications can also be sent using the following method (note that this method creates the topic if it does not exist)

def notificationService

(...)

def topic = "Wacky stuff" def message = "Heave-ho!" def scheduledDate = new Date() + 5 sendNotification(topic, message, scheduledDate)

Eventually a user may to unsubscribe an event, the NotificationService also provides a convenience method for that:

def notificationService

(...)

def subscriber = com.myapp.MySubscriber.get(subscriberId) def topic = NotificationTopic.findByTopic(defaultTopic) notificationService.unsubscribeTopic(subscriber, topic)

Configuration

If the default email channel is to be used, then the grails mail plugin should be configured. Please refer to: http://www.grails.org/plugin/mail

Default communication channels:

The default communication channels are listed in the ChannelType enum. Currently there only is support for e-mail notifications.

Implementing custom communication channels:

Custom channels are simply groovy/java classes that implement the IChannelSender interface. To implement a channel simply add a new class that implements that interface to the src/groovy (or src/java) and give its canonical name when instancing a new channel. Example:

Implementation tips:

A communication channel can be implemented as a POJO (or groovy object), and it is recommended that they are placed in the src/java or src/groovy directories of your project. If you need to use grails services (e.g. the mailService) in your custom channels, remember to use the grails application context to get them. Do not instance services using "new". Example:

class MyChannelImplementation implements IChannelSender{

def service;

public MyChannelImplementation(){ ApplicationContext context = (ApplicationContext)ApplicationHolder.getApplication().getMainContext(); this.service = (SomeService)context.getBean("someService") }

public void send(Notification notification, String destination){ … } }

Future work:

  • Add more tests
  • Add new sample applications, e.g. using the twitter api