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