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}