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   /**
047     * Constructs an instance of this event.
048     * @param src the Object that is the source of the event.
049     * @param type   the event type.
050     */
051    public WikiEvent( Object src, int type )
052    {
053        super( src );
054        m_when = System.currentTimeMillis();
055        setType( type );
056    }
057    
058    /**
059     * Convenience method that returns the typed object to which the event applied.
060     * 
061     * @return the typed object to which the event applied.
062     */
063    @SuppressWarnings("unchecked")
064    public <T> T getSrc()
065    {
066        return (T) super.getSource();
067    }
068
069
070    /**
071     *  Returns the timestamp of when this WikiEvent occurred.
072     *
073     * @return this event's timestamp
074     * @since 2.4.74
075     */
076    public long getWhen()
077    {
078        return m_when;
079    }
080
081
082   /**
083     * Sets the type of this event. Validation of acceptable
084     * type values is the responsibility of each subclass.
085     *
086     * @param type      the type of this WikiEvent.
087     */
088    protected void setType( int type )
089    {
090        m_type = type;
091    }
092
093
094   /**
095     * Returns the type of this event.
096     *
097     * @return  the type of this WikiEvent. See the enumerated values
098     *          defined in {@link org.apache.wiki.event.WikiEvent}).
099     */
100    public int getType()
101    {
102        return m_type;
103    }
104
105
106   /** Returns a String (human-readable) description of an event type.
107     * This should be subclassed as necessary.
108     * @return the String description
109     */
110    public String getTypeDescription()
111    {
112        switch ( m_type )
113        {
114            case ERROR:                return "exception or error event";
115            case UNDEFINED:            return "undefined event type";
116            default:                   return "unknown event type (" + m_type + ")";
117        }
118    }
119
120
121   /**
122     * Returns true if the int value is a valid WikiEvent type.
123     * Because the WikiEvent class does not itself any event types,
124     * this method returns true if the event type is anything except
125     * {@link #ERROR} or {@link #UNDEFINED}. This method is meant to
126     * be subclassed as appropriate.
127     * 
128     * @param type The value to test.
129     * @return true, if the value is a valid WikiEvent type.
130     */
131    public static boolean isValidType( int type )
132    {
133        return type != ERROR && type != UNDEFINED;
134    }
135
136
137    /**
138     * Returns a textual representation of an event type.
139     * @return the String representation
140     */
141    public String eventName()
142    {
143        switch( m_type )
144        {
145            case ERROR:                return "ERROR";
146            case UNDEFINED:            return "UNDEFINED";
147            default:                   return "UNKNOWN (" + m_type + ")";
148        }
149    }
150
151    /**
152     * Prints a String (human-readable) representation of this object.
153     * This should be subclassed as necessary.
154     * @see java.lang.Object#toString()
155     * @return the String representation
156     */
157    public String toString()
158    {
159        StringBuilder out = new StringBuilder();
160        out.append( "WikiEvent." );
161        out.append( eventName() );
162        out.append( " [source=" );
163        out.append( getSource().toString() );
164        out.append( "]" );
165        return out.toString();
166    }
167
168}