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
022import java.util.EventObject;
023
024/**
025 * Abstract parent class for wiki events.
026 *
027 * @since 2.3.79
028 */
029public abstract class WikiEvent extends EventObject {
030
031    private static final long serialVersionUID = 1829433967558773960L;
032
033    /** Indicates a exception or error state. */
034    public static final int ERROR          = -99;
035
036    /** Indicates an undefined state. */
037    public static final int UNDEFINED      = -98;
038
039    private int m_type = UNDEFINED;
040
041    private final long m_when;
042
043    // ............
044
045    /**
046     * Constructs an instance of this event.
047     *
048     * @param src the Object that is the source of the event.
049     * @param type the event type.
050     */
051    public WikiEvent( final Object src, final int type ) {
052        super( src );
053        m_when = System.currentTimeMillis();
054        setType( type );
055    }
056    
057    /**
058     * Convenience method that returns the typed object to which the event applied.
059     * 
060     * @return the typed object to which the event applied.
061     */
062    @SuppressWarnings("unchecked")
063    public < T > T getSrc() {
064        return ( T )super.getSource();
065    }
066
067   /**
068    *  Returns the timestamp of when this WikiEvent occurred.
069    *
070    * @return this event's timestamp
071    * @since 2.4.74
072    */
073   public long getWhen() {
074       return m_when;
075   }
076
077    /**
078     * Sets the type of this event. Validation of acceptable type values is the responsibility of each subclass.
079     *
080     * @param type the type of this WikiEvent.
081     */
082    protected void setType( final int type ) {
083        m_type = type;
084    }
085
086    /**
087     * Returns the type of this event.
088     *
089     * @return the type of this WikiEvent. See the enumerated values defined in {@link org.apache.wiki.event.WikiEvent}).
090     */
091    public int getType() {
092        return m_type;
093    }
094
095    /**
096     * Returns a String (human-readable) description of an event type. This should be subclassed as necessary.
097     *
098     * @return the String description
099     */
100    public String getTypeDescription() {
101        switch( m_type ) {
102            case ERROR:     return "exception or error event";
103            case UNDEFINED: return "undefined event type";
104            default:        return "unknown event type (" + m_type + ")";
105        }
106    }
107
108    /**
109     * Returns true if the int value is a valid WikiEvent type. Because the WikiEvent class does not itself any event types,
110     * this method returns true if the event type is anything except {@link #ERROR} or {@link #UNDEFINED}. This method is meant to
111     * be subclassed as appropriate.
112     * 
113     * @param type The value to test.
114     * @return true, if the value is a valid WikiEvent type.
115     */
116    public static boolean isValidType( final int type ) {
117        return type != ERROR && type != UNDEFINED;
118    }
119
120
121    /**
122     * Returns a textual representation of an event type.
123     *
124     * @return the String representation
125     */
126    public String eventName() {
127        switch( m_type ) {
128            case ERROR:     return "ERROR";
129            case UNDEFINED: return "UNDEFINED";
130            default:        return "UNKNOWN (" + m_type + ")";
131        }
132    }
133
134    /**
135     * Prints a String (human-readable) representation of this object. This should be subclassed as necessary.
136     *
137     * @see java.lang.Object#toString()
138     * @return the String representation
139     */
140    public String toString() {
141        return "WikiEvent." + eventName() + " [source=" + getSource().toString() + "]";
142    }
143
144}