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 020package 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.pages.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.FilterManager}, 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 */ 087public 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.pages.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.pages.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.FilterManager}. */ 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.FilterManager}. */ 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.FilterManager}. */ 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.FilterManager}. */ 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.FilterManager}. */ 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.FilterManager}. */ 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.FilterManager}. */ 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.FilterManager}. */ 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