    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. Typically this is the WikiEngine
    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}