The WikiEvents package (com.ecyrd.jspwiki.event.*) provides an events API and implementation for JSPWiki. The first version of the WikiEvents API was built on the 2.2.20 code base, migrated to 2.2.27, and as of 2.4.102 is now part of the JSPWiki distribution. The code is relatively stable (i.e., no substantial changes have occurred since its inception).

The package is built of these components:

And the abstract WikiEvent class and some of its subclasses:

-- MurrayAltheim

Event Types#

The events API contains a number of core event types, all subclasses of WikiEvent, including WikiEngineEvent, WikiPageEvent, WikiSecurityEvent and WorkflowEvent.


This is the abstract class that all WikiEvents must subclass. Every WikiEvent class defines one or more types, and includes two forms of description of those types, raw event name (obtained from eventName(), e.g., "SHUTDOWN") and the human-readable type description (obtained from getTypeDescription(), e.g., "wiki engine shutting down"). The WikiEvent class defines two types that are in effect error conditions:

  • error : an exception or error event
  • undefined : an undefined event type


WikiEngineEvent is a sublass of WikiEvent meant to capture the initialization and shutdown of the WikiEngine so you can hook things onto those periods in its lifecycle. It defines the following event types:

  • initializing : fired at the beginning of the initialization phase
  • initialized : fired after the engine has finished initialization
  • shutdown : fired at the beginning of shutting down
  • stopped : fired after the engine has shut down


WikiPageEvent is a subclass of WikiEvent that considers the processing of the page in terms of various "process phases," which are fired depending on whether one is viewing or editing pages, etc. This event class defines the following event types:
  • pre-translate : fired during the filtering that occurs prior to translation
  • post-translate : fired after the filtering that occurs prior to translation
  • pre-save : fired prior to the point at which the page is saved to the repository
  • post-save : fired after the point at which the page is saved to the repository
  • lock : fired just prior to the page lock being requested
  • unlock : fired after the page lock has been released
  • page requested : fired prior to the page processing, just after the page has been requested
  • page delivered : fired after all page processing has been completed for a request
  • security event : covers the myriad of different security event types, fired at various times during login, etc.


WikiSecurityEvent is a sublass of WikiEvent for security events: login/logout, wiki group adds/changes, and authorization decisions. When a WikiSecurityEvent is constructed, the security logger is notified. It defines the event types as described below.

These events are logged with priority ERROR:

  • login failed - bad credential or password : When a login fails due to wrong username or password.

These events are logged with priority WARN:

  • login failed - credential expired : When a login fails due to credential expiration.
  • login failed - account expired : When a login fails due to account expiration.

These events are logged with priority INFO:

  • login authenticated : When a user authenticates with a username and password, or via container auth.
  • logout : When a user logs out.
  • session expired : When a session expires.
  • user profile name changed : When a user profile name changes.

These events are not logged:

  • access allowed : When access to a resource is allowed.
  • access denied : When access to a resource is allowed.
  • login initiated : When a user's attempts to log in as guest, via cookies, using a password or otherwise.
  • login anonymous : When a user first accesses JSPWiki, but before logging in or setting a cookie.
  • login asserted : When a user sets a cookie to assert their identity.
  • user profile saved : When a user profile is saved.
  • add group : When a new wiki group is added.
  • remove group : When a wiki group is deleted.
  • clear all groups : When all wiki groups are removed from GroupDatabase.

These events no longer exist:

  • add group member : DESCRIPTION TBD
  • remove group member : DESCRIPTION TBD
  • clear all members from group : DESCRIPTION TBD


WorkflowEvent is a subclass of WikiEvent indicating a state change to a Workflow: started, running, waiting, completed, aborted. These correspond exactly to the states described in the Workflow class. All events are logged with priority INFO.

It defines the following event types:

  • workflow created : After Workflow instantiation.
  • workflow started : After the Workflow has been instantiated, but before it has been started using Workflow.start() method.
  • workflow running : After the Workflow has been started (or re-started) using the Workflow.start() method, but before it has finished processing all Steps.
  • workflow waiting : When the Workflow has temporarily paused, for example because of a pending Decision.
  • workflow completed : After the Workflow has finished processing all Steps, without errors.
  • workflow aborted : If a Step has elected to abort the Workflow.

Workflow is required for document control, checking/approving attachments, and filling and approving forms. Although strictly not a standard wiki function it is required in any project or enterprise CMS. Wiki does full document and version control of unstructured and generally unrestricted editing of content for the purpose of collaboration and in this context it is useful in an enterprise context. Wiki has the ability to restrict access. Workflow is just an additional sequential restriction on access to wiki collaboration. Integrating workflow into JSPWiki will be a huge benefit to JSPWiki users because it will fill in the small missing piece of functionality in enterprise application of JSPWiki.

An object subject to workflow is basically a template object which has several states each of which can have different access restrictions and which different users/groups can move to the next state (or possibly back to a previous state). Hence it isn't very different from standard wiki functions - it is just a different form of access control. Workflow objects should also be capable of setting different overall access restrictions depending on where it is viewed - for example you would want the lines in a drawing approval table to allow certain fields in each line to be updated in a "drawing entry" wiki, but you may want to view the table as read only when referred to in a "current drawings" wiki or list only approved drawings in the "approved drawings" wiki.

Although you could include workflow in JSPWiki by including a URL pointing to another application like Alfresco for example, the problem with this is that it leads to duplication of a lot of functionality, plus the need to log in twice, which is not really what people want. It is far better to include some basic workflow features in JSPWiki itself.

Should workflow be implemented by simply attaching a workflow object to another object? The workflow object would keep track of state and impose appropriate access restrictions on the object it is attached to, and show a visible indicator (tick button) which could be used by those who have access to do so to change the state. The object could also have a local flags which if set would prevent it's state and the content of the object it is attached to respectively from being changed if the object is viewed from another wiki, regardless of the access controls set in the other wiki.

TWiki implements a workflow implementation which may also be worth a look at.

--AnonymousCoward, 16-Sep-2007


There's now a PageEventFilter (extending BasicPageFilter) that fires events *during* each of the first four above phases (pre- and post- translate and save). If your processing just needs to occur sometime within any one of these page processing phases, adding a listener for these events and performing your processing upon receipt of the message is a pretty simple way to handle this.

The lock and unlock events only happen during an edit cycle, and are fired by the PageManager. The page requested event is fired once at the beginning of a page request and once at the finished processing and delivery of the page (either view or edit). These latter two are fired by the WikiServletFilter.

The first six event types (pre- and post- translate and save, lock and unlock) also fire "boundary" events at the beginning and end of each phase (e.g., POST_TRANSLATE_BEGIN and POST_TRANSLATE_END). Each of these begin and end phase events occur once per page delivery cycle, but due to the nature of JSP processing you may see multiple phases per page delivery (e.g., I see five translate phases for each page delivery).

The boundary and security events are noisy even if a listener hasn't been attached, so the implementation has been designed not to fire events if no listeners are attached to the PageManager, FilterManager, WikiServletFilter, or AuthorizationManager. This also keeps unnecessary event objects from being created. Enable the events by adding the appropriate listeners and you can receive both the "in-phase" events and any "phase boundary" events, otherwise all is quiet.


You can either enable the events at their sources in this manner or use the global enabler/disabler method in the WikiEventManager class.

I think there's possibly still more work to be done with consolidating the event management of the security events. Since I don't fully understand the implications of making those changes I've not dug that far into them yet. I've tried to design this so that there will be minimal impact on the performance of the wiki engine for the status quo of no events being fired.

-- MurrayAltheim



See also: WikiEventManager

Add new attachment

Only authorized users are allowed to upload new attachments.

List of attachments

Kind Attachment Name Size Version Date Modified Author Change note
zip 26.0 kB 1 25-Jun-2005 16:31 MurrayAltheim
« This page (revision-10) was last changed on 18-Jul-2007 07:16 by MurrayAltheim