Wiki source code of GroovyNotificationTutorial
Version 3.7 by Vincent Massol on 2009/08/29
Show last authors
| author | version | line-number | content |
|---|---|---|---|
| 1 | {{box cssClass="floatinginfobox" title="**Contents**"}}{{toc start="2" depth="4"/}}{{/box}} | ||
| 2 | |||
| 3 | = Groovy Notification Tutorial | ||
| 4 | |||
| 5 | XWiki supports notifications (a.k.a Observations) and it's possible to do some action when a document is modified, when a document's objects are modified, etc. See the full documentation in the [[Observation reference documentation>>code:Modules.ObservationModule]]. | ||
| 6 | |||
| 7 | This tutorial explains how to write a Groovy script in a wiki page that responds to document changes. More specifically whenever a wiki page is modified we log the event in the ##Main.Logger## wiki page. | ||
| 8 | |||
| 9 | == Writing the Event Listener | ||
| 10 | |||
| 11 | {{code language="java"}} | ||
| 12 | {{groovy}} | ||
| 13 | import org.xwiki.observation.* | ||
| 14 | import org.xwiki.observation.event.* | ||
| 15 | import com.xpn.xwiki.web.* | ||
| 16 | import com.xpn.xwiki.* | ||
| 17 | |||
| 18 | class LoggingEventListener implements EventListener | ||
| 19 | { | ||
| 20 | def xwiki | ||
| 21 | def context | ||
| 22 | |||
| 23 | LoggingEventListener(xwiki, context) | ||
| 24 | { | ||
| 25 | this.xwiki = xwiki | ||
| 26 | this.context = context | ||
| 27 | } | ||
| 28 | |||
| 29 | String getName() | ||
| 30 | { | ||
| 31 | // The unique name of this event listener | ||
| 32 | return "logging" | ||
| 33 | } | ||
| 34 | |||
| 35 | List<Event> getEvents() | ||
| 36 | { | ||
| 37 | // The list of events this listener listens to | ||
| 38 | return Arrays.asList(new DocumentUpdateEvent()) | ||
| 39 | } | ||
| 40 | |||
| 41 | // Called by the Observation Manager when an event matches the list of events returned | ||
| 42 | // by getEvents() | ||
| 43 | void onEvent(Event event, Object source, Object data) | ||
| 44 | { | ||
| 45 | // Prevent infinite recursion since in this example we log to wiki page which | ||
| 46 | // triggers a document change... :) | ||
| 47 | if (source.fullName != "Main.Logger") { | ||
| 48 | def document = xwiki.getDocument("Main.Logger") | ||
| 49 | document.setContent("${document.getContent()}\n${source.fullName} has changed") | ||
| 50 | document.save("Logging event", true) | ||
| 51 | } | ||
| 52 | } | ||
| 53 | } | ||
| 54 | |||
| 55 | // Register against the Observation Manager | ||
| 56 | def observation = Utils.getComponent(ObservationManager.class) | ||
| 57 | observation.removeListener("logging") | ||
| 58 | def listener = new LoggingEventListener(xwiki, xcontext) | ||
| 59 | observation.addListener(listener) | ||
| 60 | |||
| 61 | {{/groovy}} | ||
| 62 | {{/code}} | ||
| 63 | |||
| 64 | == Older Notification Tutorial | ||
| 65 | |||
| 66 | This tutorial uses the old notification mechanism to listen to events (now deprecated in XWiki 2.0). You should follow it if you're using a version of XWiki Enterprise prior to 2.0. | ||
| 67 | |||
| 68 | In order to listen to events you need to write 2 pages: | ||
| 69 | * A page containing a Groovy class that registers against the XWiki Event Manager and that has the method to be called when the event happens. | ||
| 70 | * Another page that parses the Groovy page and loads it in the Groovy context. | ||
| 71 | |||
| 72 | === Groovy Notification Class | ||
| 73 | |||
| 74 | Your Groovy needs to extend the ##com.xpn.xwiki.notify.XWikiDocChangeNotificationInterface## as shown below. | ||
| 75 | |||
| 76 | {{code language="java"}} | ||
| 77 | /* Groovy Class #* */ | ||
| 78 | |||
| 79 | import com.xpn.xwiki.api.*; | ||
| 80 | import com.xpn.xwiki.notify.*; | ||
| 81 | import com.xpn.xwiki.*; | ||
| 82 | import com.xpn.xwiki.doc.*; | ||
| 83 | |||
| 84 | public class MyGroovyClass implements XWikiDocChangeNotificationInterface | ||
| 85 | { | ||
| 86 | def xwiki; | ||
| 87 | def rule; | ||
| 88 | |||
| 89 | public MyGroovyClass() | ||
| 90 | { | ||
| 91 | this.rule = new DocChangeRule(this); | ||
| 92 | } | ||
| 93 | |||
| 94 | public void init(xwiki) | ||
| 95 | { | ||
| 96 | this.xwiki = xwiki; | ||
| 97 | xwiki.getXWiki().getNotificationManager().addGeneralRule(this.rule); | ||
| 98 | } | ||
| 99 | |||
| 100 | public void cleanup() | ||
| 101 | { | ||
| 102 | xwiki.getXWiki().getNotificationManager().removeGeneralRule(this.rule); | ||
| 103 | } | ||
| 104 | |||
| 105 | public void notify(XWikiNotificationRule rule, XWikiDocument newdoc, XWikiDocument olddoc, | ||
| 106 | int event, XWikiContext context) | ||
| 107 | { | ||
| 108 | // Do some action here. | ||
| 109 | } | ||
| 110 | } | ||
| 111 | |||
| 112 | /* *# */ | ||
| 113 | {{/code}} | ||
| 114 | |||
| 115 | In this example we've used a ##DocChangeRule## rule. There are also [[other rules>>http://svn.xwiki.org/svnroot/xwiki/platform/core/trunk/xwiki-core/src/main/java/com/xpn/xwiki/notify/]]. | ||
| 116 | |||
| 117 | === Calling the Groovy Class | ||
| 118 | |||
| 119 | {{code}} | ||
| 120 | #set($mygroovyclass = $xwiki.parseGroovyFromPage("MySpace.MyGroovyClass")) | ||
| 121 | $mygroovyclass.init($xwiki) | ||
| 122 | {{/code}} | ||
| 123 | |||
| 124 | === Example: IRC notification on document change | ||
| 125 | |||
| 126 | {{velocity}}{{html}} | ||
| 127 | #warning("The code below uses the parseGroovyFromPage method which takes 2 parameters. The second one is the name of page containing JARS as attachments. These JARs are put in the classloader used by Groovy when parsing the page. This feature is only working in XWiki Core 1.3 and later.") | ||
| 128 | {{/html}}{{/velocity}} | ||
| 129 | |||
| 130 | * **Step 1**: Groovy Class ((( | ||
| 131 | {{code language="java"}} | ||
| 132 | /* Groovy Class #* */ | ||
| 133 | |||
| 134 | import org.jibble.pircbot.*; | ||
| 135 | import java.util.*; | ||
| 136 | import com.xpn.xwiki.api.*; | ||
| 137 | import com.xpn.xwiki.notify.*; | ||
| 138 | import com.xpn.xwiki.*; | ||
| 139 | import com.xpn.xwiki.doc.*; | ||
| 140 | |||
| 141 | public class XWikiBot extends PircBot implements XWikiDocChangeNotificationInterface | ||
| 142 | { | ||
| 143 | def xwiki; | ||
| 144 | def channel; | ||
| 145 | def rule; | ||
| 146 | |||
| 147 | public XWikiBot() | ||
| 148 | { | ||
| 149 | this.setName("xwikibot"); | ||
| 150 | this.rule = new DocChangeRule(this); | ||
| 151 | } | ||
| 152 | |||
| 153 | public void init(xwiki, channel) | ||
| 154 | { | ||
| 155 | this.xwiki = xwiki; | ||
| 156 | this.channel = channel; | ||
| 157 | xwiki.getXWiki().getNotificationManager().addGeneralRule(this.rule); | ||
| 158 | } | ||
| 159 | |||
| 160 | public void cleanup() | ||
| 161 | { | ||
| 162 | xwiki.getXWiki().getNotificationManager().removeGeneralRule(this.rule); | ||
| 163 | } | ||
| 164 | |||
| 165 | public void notify(XWikiNotificationRule rule, XWikiDocument newdoc, XWikiDocument olddoc, | ||
| 166 | int event, XWikiContext context) | ||
| 167 | { | ||
| 168 | sendMessage(this.channel, newdoc.getFullName() + " was modified - " + newdoc.getExternalURL("view", context)); | ||
| 169 | } | ||
| 170 | } | ||
| 171 | |||
| 172 | /* *# */ | ||
| 173 | {{/code}} | ||
| 174 | ))) | ||
| 175 | * **Step 2**: Add the PircBot JAR as an attachment to the ##MySpace.MyGroovyClass## page created in step 1. | ||
| 176 | * **Step 3**: Calling page ((( | ||
| 177 | {{code}} | ||
| 178 | ## Start by looking for a bot in the servlet context | ||
| 179 | #set ($sc = $context.getContext().getEngineContext().getServletContext()) | ||
| 180 | |||
| 181 | ## If the bot isn't in the servlet context, start the bot and put in the context | ||
| 182 | #set ($bot = $sc.getAttribute("ircbot")) | ||
| 183 | #if (!$bot) | ||
| 184 | Bot is not started, starting it... | ||
| 185 | #set($bot = $xwiki.parseGroovyFromPage("MySpace.MyGroovyClass", "MySpace.MyGroovyClass")) | ||
| 186 | #set ($channel = "#xwiki") | ||
| 187 | $bot.init($xwiki, $channel) | ||
| 188 | $bot.connect("irc.freenode.net") | ||
| 189 | $bot.joinChannel($channel) | ||
| 190 | $sc.setAttribute("ircbot", $bot) | ||
| 191 | Bot started! | ||
| 192 | |||
| 193 | ## If the parameter passed is stop then stop the bot | ||
| 194 | #elseif ($request.action && $request.action == "stop") | ||
| 195 | $bot.cleanup() | ||
| 196 | $bot.disconnect() | ||
| 197 | $sc.setAttribute("ircbot", null) | ||
| 198 | Bot disconnected! | ||
| 199 | |||
| 200 | #else | ||
| 201 | Bot already started, doing nothing... | ||
| 202 | |||
| 203 | #end | ||
| 204 | {{/code}} | ||
| 205 | ))) | ||
| 206 | * **Step 4**: Creating a Scheduler job so that the Bot is restarted automatically if the server is restarted for example. ((( | ||
| 207 | |||
| 208 | Create a Scheduler job, set it to run every 5 minutes for example and use the following Groovy script in the job: | ||
| 209 | |||
| 210 | {{code language="java"}} | ||
| 211 | // Start by looking for a bot in the servlet context | ||
| 212 | def sc = context.getEngineContext().getServletContext() | ||
| 213 | |||
| 214 | // If the bot isn't in the servlet context, start the bot and put in the context | ||
| 215 | def bot = sc.getAttribute("ircbot") | ||
| 216 | if (bot == null) { | ||
| 217 | // Bot is not started, starting it... | ||
| 218 | bot = xwiki.parseGroovyFromPage("MySpace.MyGroovyClass", "MySpace.MyGroovyClass") | ||
| 219 | def channel = "#xwiki" | ||
| 220 | bot.init(xwiki, channel) | ||
| 221 | bot.connect("irc.freenode.net") | ||
| 222 | bot.joinChannel(channel) | ||
| 223 | sc.setAttribute("ircbot", bot) | ||
| 224 | // Bot started! | ||
| 225 | } | ||
| 226 | {{/code}} | ||
| 227 | ))) |
