Class designation: Interface org.apache.wiki.event.WikiEvent extends java.util.EventObject

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
WikiSecurityEvent.GROUP_CLEAR_GROUPS does not appear to be fired anywhere. WorkflowEvent.CREATED and WorkflowEvent.STARTED are not currently fired, only used as states by the WorkflowManager.

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.D