A WikiEvent is a type of Java EventObject, and is used to notify interested parties that something has happened within the WikiEngine. This is done by attaching a WikiEventListener for events, the listener generally contains filters to look for certain event classes or types. The listener is added to a singleton manager called a WikiEventManager, which handles all WikiEvent within a JVM (i.e., even for multiple WikiEngines).

A step-by-step example of how to use WikiEvent can be found on the WikiEngineEvent page.

Prior to version 2.4.20 there was no event handling in JSPWiki. The org.apache.wiki.event.* package was written to provide a complete event handling solution and is now part of the 2.4.x and SVN distributions.

See: WikiEngineEvent, WikiPageEvent, WikiSecurityEvent, WorkflowEvent

org.apache.wiki.event.* package#

The org.apache.wiki.event.* package consists of the following classes:

• WikiEvent : the abstract event base class (all WikiEvent types extend this class)
• WikiEventListener : the listener interface (just has one actionPerformed() method)
• WikiEventManager : the singleton event manager
• WikiEventUtils : a static utility class providing a filterable add listener method
• PageEventFilter : a filter that fires page events for various stages in the change to a wiki page

WikiEvent Classes#

The following classes extend the abstract WikiEvent class and are hence the kinds of events you'll see spinning around within JSPWiki's events snowglobe:

event class	fired by	types	purpose
WikiEngineEvent	WikiEngine	INITIALIZING, INITIALIZED, SHUTDOWN, STOPPED	changes of state within the WikiEngine
WikiPageEvent	WikiServletFilter	PAGE_REQUESTED, PAGE_DELIVERED	page delivery events
WikiPageEvent	PageEventFilter	PRE_TRANSLATE, POST_TRANSLATE, PRE_SAVE, POST_SAVE	page state change events
WikiPageEvent	FilterManager	PRE_TRANSLATE_BEGIN, PRE_TRANSLATE_END, POST_TRANSLATE_BEGIN, POST_TRANSLATE_END, PRE_SAVE_BEGIN, PRE_SAVE_END, POST_SAVE_BEGIN, POST_SAVE_END	page translate and save events
WikiPageEvent	PageManager	PAGE_LOCK, PAGE_UNLOCK, PAGE_DELETE_REQUEST, PAGE_DELETED	page locking and deletion events
WikiSecurityEvent	AuthenticationManager	LOGIN_INITIATED, LOGIN_ANONYMOUS, LOGIN_ASSERTED, LOGIN_AUTHENTICATED, LOGOUT, LOGIN_ACCOUNT_EXPIRED, LOGIN_CREDENTIAL_EXPIRED, LOGIN_FAILED	login & logout events
WikiSecurityEvent	AuthorizationManager	ACCESS_ALLOWED, ACCESS_DENIED	access allowed or denied events
WikiSecurityEvent	GroupManager	GROUP_ADD, GROUP_REMOVE	group add & remove events
WikiSecurityEvent	SessionMonitor	SESSION_EXPIRED	session expired events
WikiSecurityEvent	UserManager	PROFILE_SAVE	save profile events
WorkflowEvent	Workflow	RUNNING, WAITING, COMPLETED, ABORTED	workflow events

WikiEventManager#

The WikiEventManager is a singleton object (i.e., there is only one). Access to it is via:

    WikiEventManager mgr = WikiEventManager.getInstance();

but you won't generally need this, as all of the commonly-used methods are static.

To add a listener for all WikiEvent you simply call with the object you want

    WikiEventManager.addWikiEventListener(object,listener);

Firing an event is pretty simple. Here's a typical method (this will vary slightly depending on the event type; shown below fires a WikiPageEvent):

    protected final void fireEvent( int type, WikiContext context )
    {
        if ( WikiEventManager.isListening(this) )
        {
            WikiPageEvent event = new WikiPageEvent(
                    context.getEngine(),
                    type,
                    context.getPage().getName());
            WikiEventManager.fireEvent(this,event);
        }
    }

The isListening(this) method returns true if you've previously added a listener for the object.

Preloading Listeners#

Because we wanted to embed JSPWiki's WikiEngine in Ceryle (a standalone Java application), such that upon launching the application the WikiEngine would load if the Web server was running and inform Ceryle of its existence (we needed to do this so we could intercept the initialization sequence to modify various properties such as storage locations, etc.). This required adding event listeners to objects that didn't yet exist. The WikiEventManager is designed so that its event delegates can be attached to a Java class, so that the first time the class is instantiated the already-existing listener is attached to the new class. In this way we can listen for things as they start up.

  WikiEventManager.addWikiEventListener(WikiEngine.class,listener);

Each time the above method is called another listener is added to the WikiEventManager's preload cache.

You can do this with any class if you expect one to be created and want to create a listener for it prior to its existence. [If you're wondering what the listener in the example looks like, check out the WikiEventListener page.] — Murray Altheim

---

See also: WikiEventListener, WikiEventManager, WikiEngineEvent Example

---

Category.Documentation