001 /*
002 Licensed to the Apache Software Foundation (ASF) under one
003 or more contributor license agreements. See the NOTICE file
004 distributed with this work for additional information
005 regarding copyright ownership. The ASF licenses this file
006 to you under the Apache License, Version 2.0 (the
007 "License"); you may not use this file except in compliance
008 with the License. You may obtain a copy of the License at
009
010 http://www.apache.org/licenses/LICENSE-2.0
011
012 Unless required by applicable law or agreed to in writing,
013 software distributed under the License is distributed on an
014 "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
015 KIND, either express or implied. See the License for the
016 specific language governing permissions and limitations
017 under the License.
018 */
019
020 package org.apache.wiki.event;
021
022
023 /**
024 * WikiPageEvent indicates a change in the state or processing of a WikiPage.
025 * There are basically two types of page events:
026 * <dl>
027 * <dt><b>Phase Boundary Events</b></dt>
028 * <dd>Those considered as "beginning-of-phase", and those as "end-of-phase"
029 * events (as designated by <tt>*_BEGIN</tt> and <tt>*_END</tt>), as
030 * generated by the WikiEngine. The phases include pre-save, post-save,
031 * pre-translate, and post-translate.
032 * </dd>
033 * <dt><b>In-Phase Events</b></dt>
034 * <dd>In-phase events are generated as specific events from the
035 * PageEventFilter (or elsewhere), on a per-listener basis. There may
036 * be many such events during a particular phase.
037 * </dd>
038 * </dl>
039 * <p>
040 * E.g., a typical event sequence for the pre-translate phase would be:
041 * </p>
042 * <ol>
043 * <li>PRE_TRANSLATE_BEGIN</li>
044 * <li>PRE_TRANSLATE</li>
045 * <li>PRE_TRANSLATE</li>
046 * <li>...</li>
047 * <li>PRE_TRANSLATE_END</li>
048 * </ol>
049 *
050 * <h2>Notes</h2>
051 *
052 * <h3>Page Requested and Delivered Events</h3>
053 * <p>
054 * These two events are fired once per page request, at the beginning
055 * and after delivery of the page (respectively). They are generated
056 * by the {@link org.apache.wiki.ui.WikiServletFilter}.
057 * </p>
058 *
059 * <h3>Page Lock and Unlock Events</h3>
060 * <p>
061 * Page lock and unlock events occur only once during an editing session,
062 * so there are no begin and end events. They are generated
063 * by the {@link org.apache.wiki.PageManager}.
064 * </p>
065 *
066 * <h3>WikiPageEvents</h3>
067 * <p>
068 * Other WikiPageEvents include both <i>phase boundary</i> and <i>in-phase</i>
069 * events for saving, pre- and post-translating content. These are very noisy
070 * event types, but are not fired unless a listener is available. They are
071 * generated by the {@link org.apache.wiki.filters.DefaultFilterManager},
072 * {@link org.apache.wiki.event.PageEventFilter}, and potentially other
073 * implementing classes.
074 * </p>
075 *
076 * <h3>Firing Order and Phase Boundaries</h3>
077 * <p>
078 * Note that due to the asynchronous nature of event processing, any threads
079 * spawned by such events will not necessarily have completed during their
080 * specific phase; we can assume only that no more events of that phase will
081 * be fired after its <tt>*_END</tt> event has been fired.
082 * </p>
083 *
084 * @see org.apache.wiki.event.WikiEvent
085 * @since 2.4.20
086 */
087 public class WikiPageEvent extends WikiEvent
088 {
089 // PAGE LOCKING EVENTS ...
090
091 /**
092 *
093 */
094 private static final long serialVersionUID = 1L;
095
096 /** Indicates a page lock event. This is based on events
097 * generated by {@link org.apache.wiki.PageManager}. */
098 public static final int PAGE_LOCK = 10;
099
100 /** Indicates a page unlock event. This is based on events
101 * generated by {@link org.apache.wiki.PageManager}. */
102 public static final int PAGE_UNLOCK = 11;
103
104 // PRE_TRANSLATE .........
105
106 /** Indicates the beginning of all wiki pre-translate page events. This is based
107 * on events generated by {@link org.apache.wiki.filters.DefaultFilterManager}. */
108 public static final int PRE_TRANSLATE_BEGIN = 12;
109
110 /** Indicates a wiki pre-translate page event. This is based on events
111 * generated by {@link org.apache.wiki.event.PageEventFilter}. */
112 public static final int PRE_TRANSLATE = 13;
113
114 /** Indicates the end of all wiki pre-translate page events. This is based
115 * on events generated by {@link org.apache.wiki.filters.DefaultFilterManager}. */
116 public static final int PRE_TRANSLATE_END = 14;
117
118 // POST_TRANSLATE ........
119
120 /** Indicates the beginning of all wiki post-translate page events. This is based
121 * on events generated by {@link org.apache.wiki.filters.DefaultFilterManager}. */
122 public static final int POST_TRANSLATE_BEGIN = 15;
123
124 /** Indicates a wiki post-translate page event. This is based on events
125 * generated by {@link org.apache.wiki.event.PageEventFilter}. */
126 public static final int POST_TRANSLATE = 16;
127
128 /** Indicates the end of all wiki post-translate page events. This is based
129 * on events generated by {@link org.apache.wiki.filters.DefaultFilterManager}. */
130 public static final int POST_TRANSLATE_END = 17;
131
132 // PRE_SAVE ..............
133
134 /** Indicates the beginning of all wiki pre-save page events. This is based
135 * on events generated by {@link org.apache.wiki.filters.DefaultFilterManager}. */
136 public static final int PRE_SAVE_BEGIN = 18;
137
138 /** Indicates a wiki pre-save page event. This is based on events
139 * generated by {@link org.apache.wiki.event.PageEventFilter}. */
140 public static final int PRE_SAVE = 19;
141
142 /** Indicates the end of all wiki pre-save page events. This is based
143 * on events generated by {@link org.apache.wiki.filters.DefaultFilterManager}. */
144 public static final int PRE_SAVE_END = 20;
145
146 // POST_SAVE .............
147
148 /** Indicates the beginning of all wiki post-save page events. This is based
149 * on events generated by {@link org.apache.wiki.filters.DefaultFilterManager}. */
150 public static final int POST_SAVE_BEGIN = 21;
151
152 /** Indicates a wiki post-save page event. This is based on events
153 * generated by {@link org.apache.wiki.event.PageEventFilter}. */
154 public static final int POST_SAVE = 22;
155
156 /** Indicates the end of all wiki post-save page events. This is based
157 * on events generated by {@link org.apache.wiki.filters.DefaultFilterManager}. */
158 public static final int POST_SAVE_END = 23;
159
160 // PAGE REQUESTS .........
161
162 /** Indicates a wiki page request event (the start of a request). This is based
163 * on events generated by {@link org.apache.wiki.ui.WikiServletFilter}. */
164 public static final int PAGE_REQUESTED = 24;
165
166 /** Indicates a wiki page delivery event (the end of a request). This is based
167 * on events generated by {@link org.apache.wiki.ui.WikiServletFilter}. */
168 public static final int PAGE_DELIVERED = 25;
169
170 /** Indicates a wiki page delete event (the beginning of a delete request).
171 * This is based on events generated by {@link org.apache.wiki.ui.WikiServletFilter}.
172 * @since 2.4.65 */
173 public static final int PAGE_DELETE_REQUEST = 26;
174
175 /** Indicates a wiki page deleted event (after the delete has been completed).
176 * This is based on events generated by {@link org.apache.wiki.ui.WikiServletFilter}.
177 * @since 2.4.65 */
178 public static final int PAGE_DELETED = 27;
179
180 private String m_pagename = null;
181
182 // ............
183
184
185 /**
186 * Constructs an instance of this event.
187 * @param src the Object that is the source of the event.
188 * @param type the type of the event (see the enumerated int values defined
189 * in {@link org.apache.wiki.event.WikiEvent}).
190 * @param pagename the WikiPage being acted upon.
191 */
192 public WikiPageEvent( Object src, int type, String pagename )
193 {
194 super( src, type );
195 m_pagename = pagename;
196 }
197
198
199 /**
200 * Returns the Wiki page name associated with this event.
201 * This may be null if unavailable.
202 *
203 * @return the Wiki page name associated with this WikiEvent, or null.
204 */
205 public String getPageName()
206 {
207 return m_pagename;
208 }
209
210
211 /**
212 * Returns true if the int value is a WikiPageEvent type.
213 */
214 public static boolean isValidType( int type )
215 {
216 return type >= PAGE_LOCK && type <= PAGE_DELETED;
217 }
218
219
220 /**
221 * Returns a textual representation of the event type.
222 * @return a String representation of the type
223 */
224 public String eventName()
225 {
226 switch ( getType() )
227 {
228 case PAGE_LOCK: return "PAGE_LOCK";
229 case PAGE_UNLOCK: return "PAGE_UNLOCK";
230
231 case PRE_TRANSLATE_BEGIN: return "PRE_TRANSLATE_BEGIN";
232 case PRE_TRANSLATE: return "PRE_TRANSLATE";
233 case PRE_TRANSLATE_END: return "PRE_TRANSLATE_END";
234
235 case POST_TRANSLATE_BEGIN: return "POST_TRANSLATE_BEGIN";
236 case POST_TRANSLATE: return "POST_TRANSLATE";
237 case POST_TRANSLATE_END: return "POST_TRANSLATE_END";
238
239 case PRE_SAVE_BEGIN: return "PRE_SAVE_BEGIN";
240 case PRE_SAVE: return "PRE_SAVE";
241 case PRE_SAVE_END: return "PRE_SAVE_END";
242
243 case POST_SAVE_BEGIN: return "POST_SAVE_BEGIN";
244 case POST_SAVE: return "POST_SAVE";
245 case POST_SAVE_END: return "POST_SAVE_END";
246
247 case PAGE_REQUESTED: return "PAGE_REQUESTED";
248 case PAGE_DELIVERED: return "PAGE_DELIVERED";
249
250 case PAGE_DELETE_REQUEST: return "PAGE_DELETE_REQUEST";
251 case PAGE_DELETED: return "PAGE_DELETED";
252
253 default: return super.eventName();
254 }
255 }
256
257
258 /** Returns a human-readable description of the event type.
259 * @return a String description of the type
260 */
261 public String getTypeDescription()
262 {
263 switch ( getType() )
264 {
265 case PAGE_LOCK: return "page lock event";
266 case PAGE_UNLOCK: return "page unlock event";
267
268 case PRE_TRANSLATE_BEGIN: return "begin page pre-translate events";
269 case PRE_TRANSLATE: return "page pre-translate event";
270 case PRE_TRANSLATE_END: return "end of page pre-translate events";
271
272 case POST_TRANSLATE_BEGIN: return "begin page post-translate events";
273 case POST_TRANSLATE: return "page post-translate event";
274 case POST_TRANSLATE_END: return "end of page post-translate events";
275
276 case PRE_SAVE_BEGIN: return "begin page pre-save events";
277 case PRE_SAVE: return "page pre-save event";
278 case PRE_SAVE_END: return "end of page pre-save events";
279
280 case POST_SAVE_BEGIN: return "begin page post-save events";
281 case POST_SAVE: return "page post-save event";
282 case POST_SAVE_END: return "end of page post-save events";
283
284 case PAGE_REQUESTED: return "page requested event";
285 case PAGE_DELIVERED: return "page delivered event";
286
287 case PAGE_DELETE_REQUEST: return "page delete request event";
288 case PAGE_DELETED: return "page deleted event";
289
290 default: return super.getTypeDescription();
291 }
292 }
293
294 } // end class org.apache.wiki.event.WikiPageEvent