001: /*
002: JSPWiki - a JSP-based WikiWiki clone.
003:
004: Copyright (C) 2001-2006 Janne Jalkanen (Janne.Jalkanen@iki.fi)
005:
006: This program is free software; you can redistribute it and/or modify
007: it under the terms of the GNU Lesser General Public License as published by
008: the Free Software Foundation; either version 2.1 of the License, or
009: (at your option) any later version.
010:
011: This program is distributed in the hope that it will be useful,
012: but WITHOUT ANY WARRANTY; without even the implied warranty of
013: MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
014: GNU Lesser General Public License for more details.
015:
016: You should have received a copy of the GNU Lesser General Public License
017: along with this program; if not, write to the Free Software
018: Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
019: */
020:
021: package com.ecyrd.jspwiki.event;
022:
023: import com.ecyrd.jspwiki.WikiEngine;
024:
025: /**
026: * A utility class that adds some JSPWiki-specific functionality to the
027: * WikiEventManager (which is really a general-purpose event manager).
028: *
029: * @author Murray Altheim
030: * @since 2.4.20
031: */
032: public class WikiEventUtils {
033: /**
034: * This ungainly convenience method adds a WikiEventListener to the
035: * appropriate component of the provided client Object, to listen
036: * for events of the provided type (or related types, see the table
037: * below).
038: * <p>
039: * If the type value is valid but does not match any WikiEvent type
040: * known to this method, this will just attach the listener to the
041: * client Object. This may mean that the Object never fires events
042: * of the desired type; type-to-client matching is left to you to
043: * guarantee. Silence is golden, but not if you want those events.
044: * </p>
045: * <p>
046: * Most event types expect a WikiEngine as the client, with the rest
047: * attaching the listener directly to the supplied source object, as
048: * described below:
049: * </p>
050: * <table border="1" cellpadding="4">
051: * <tr><th>WikiEvent Type(s) </th><th>Required Source Object </th><th>Actually Attached To </th>
052: * </tr>
053: * <tr><td>any WikiEngineEvent </td><td>WikiEngine </td><td>WikiEngine </td></tr>
054: * <tr><td>WikiPageEvent.PAGE_LOCK,
055: * WikiPageEvent.PAGE_UNLOCK </td><td>WikiEngine or
056: * PageManager </td><td>PageManager </td></tr>
057: * <tr><td>WikiPageEvent.PAGE_REQUESTED,
058: * WikiPageEvent.PAGE_DELIVERED </td>
059: * <td>WikiServletFilter </td>
060: * <td>WikiServletFilter </td></tr>
061: * <tr><td>WikiPageEvent (<a href="#pbeTypes">phase boundary event</a>)</td>
062: * <td>WikiEngine </td><td>FilterManager </td></tr>
063: * <tr><td>WikiPageEvent (<a href="#ipeTypes">in-phase event</a>)</td>
064: * <tr><td>WikiPageEvent (in-phase event)</td>
065: * <td>any </td><td>source object </td></tr>
066: * <tr><td>WikiSecurityEvent </td><td>any </td><td>source object </td></tr>
067: * <tr><td>any other valid type </td><td>any </td><td>source object </td></tr>
068: * <tr><td>any invalid type </td><td>any </td><td>nothing </td></tr>
069: * </table>
070: *
071: * <p id="pbeTypes"><small><b>phase boundary event types:</b>
072: * <tt>WikiPageEvent.PRE_TRANSLATE_BEGIN</tt>, <tt>WikiPageEvent.PRE_TRANSLATE_END</tt>,
073: * <tt>WikiPageEvent.POST_TRANSLATE_BEGIN</tt>, <tt>WikiPageEvent.POST_TRANSLATE_END</tt>,
074: * <tt>WikiPageEvent.PRE_SAVE_BEGIN</tt>, <tt>WikiPageEvent.PRE_SAVE_END</tt>,
075: * <tt>WikiPageEvent.POST_SAVE_BEGIN</tt>, and <tt>WikiPageEvent.POST_SAVE_END</tt>.
076: * </small></p>
077: * <p id="ipeTypes"><small><b>in-phase event types:</b>
078: * <tt>WikiPageEvent.PRE_TRANSLATE</tt>, <tt>WikiPageEvent.POST_TRANSLATE</tt>,
079: * <tt>WikiPageEvent.PRE_SAVE</tt>, and <tt>WikiPageEvent.POST_SAVE</tt>.
080: * </small></p>
081: *
082: * <p>
083: * <b>Note:</b> The <i>Actually Attached To</i> column may also be considered as the
084: * class(es) that fire events of the type(s) shown in the <i>WikiEvent Type</i> column.
085: * </p>
086: *
087: * @see com.ecyrd.jspwiki.event.WikiEvent
088: * @see com.ecyrd.jspwiki.event.WikiEngineEvent
089: * @see com.ecyrd.jspwiki.event.WikiPageEvent
090: * @see com.ecyrd.jspwiki.event.WikiSecurityEvent
091: * @throws ClassCastException if there is a type mismatch between certain event types and the client Object
092: */
093: public static synchronized void addWikiEventListener(Object client,
094: int type, WikiEventListener listener) {
095: // Make sure WikiEventManager exists
096: WikiEventManager.getInstance();
097:
098: // first, figure out what kind of event is expected to be generated this does
099: // tie us into known types, but WikiEvent.isValidType() will return true so
100: // long as the type was set to any non-ERROR or non-UNKNOWN value
101:
102: if (WikiEngineEvent.isValidType(type)) // add listener directly to WikiEngine
103: {
104: WikiEventManager.addWikiEventListener(client, listener);
105: } else if (WikiPageEvent.isValidType(type)) // add listener to one of several options
106: {
107: if (type == WikiPageEvent.PAGE_LOCK
108: || type == WikiPageEvent.PAGE_UNLOCK) // attach to PageManager
109: {
110: if (client instanceof WikiEngine) {
111: WikiEventManager.addWikiEventListener(
112: ((WikiEngine) client).getPageManager(),
113: listener);
114: } else // if ( client instanceof PageManager ) // no filter?
115: {
116: WikiEventManager.addWikiEventListener(client,
117: listener);
118: }
119: } else if (type == WikiPageEvent.PAGE_REQUESTED
120: || type == WikiPageEvent.PAGE_DELIVERED) // attach directly to WikiServletFilter
121: {
122: WikiEventManager.addWikiEventListener(client, listener);
123: } else if (type == WikiPageEvent.PRE_TRANSLATE_BEGIN
124: || type == WikiPageEvent.PRE_TRANSLATE_END
125: || type == WikiPageEvent.POST_TRANSLATE_BEGIN
126: || type == WikiPageEvent.POST_TRANSLATE_END
127: || type == WikiPageEvent.PRE_SAVE_BEGIN
128: || type == WikiPageEvent.PRE_SAVE_END
129: || type == WikiPageEvent.POST_SAVE_BEGIN
130: || type == WikiPageEvent.POST_SAVE_END) // attach to FilterManager
131: {
132: WikiEventManager.addWikiEventListener(
133: ((WikiEngine) client).getFilterManager(),
134: listener);
135: } else //if ( type == WikiPageEvent.PRE_TRANSLATE
136: // || type == WikiPageEvent.POST_TRANSLATE
137: // || type == WikiPageEvent.PRE_SAVE
138: // || type == WikiPageEvent.POST_SAVE ) // attach to client
139: {
140: WikiEventManager.addWikiEventListener(client, listener);
141: }
142: } else if (WikiSecurityEvent.isValidType(type)) // add listener to the client
143: {
144: // currently just attach it to the client (we are ignorant of other options)
145: WikiEventManager.addWikiEventListener(client, listener);
146: } else if (WikiEvent.isValidType(type)) // we don't know what to do
147: {
148: WikiEventManager.addWikiEventListener(client, listener);
149: } else // is error or unknown
150: {
151: // why are we being called with this?
152: }
153: }
154:
155: } // end com.ecyrd.jspwiki.event.WikiEventUtils
|