001    package org.bukkit.event;
002    
003    import org.bukkit.plugin.PluginManager;
004    
005    /**
006     * Represents an event.
007     *
008     * @see PluginManager#callEvent(Event)
009     * @see PluginManager#registerEvents(Listener,Plugin)
010     */
011    public abstract class Event {
012        private String name;
013        private final boolean async;
014    
015        /**
016         * The default constructor is defined for cleaner code. This constructor
017         * assumes the event is synchronous.
018         */
019        public Event() {
020            this(false);
021        }
022    
023        /**
024         * This constructor is used to explicitly declare an event as synchronous
025         * or asynchronous.
026         *
027         * @param isAsync true indicates the event will fire asynchronously, false
028         *     by default from default constructor
029         */
030        public Event(boolean isAsync) {
031            this.async = isAsync;
032        }
033    
034        /**
035         * Convenience method for providing a user-friendly identifier. By
036         * default, it is the event's class's {@linkplain Class#getSimpleName()
037         * simple name}.
038         *
039         * @return name of this event
040         */
041        public String getEventName() {
042            if (name == null) {
043                name = getClass().getSimpleName();
044            }
045            return name;
046        }
047    
048        public abstract HandlerList getHandlers();
049    
050        /**
051         * Any custom event that should not by synchronized with other events must
052         * use the specific constructor. These are the caveats of using an
053         * asynchronous event:
054         * <ul>
055         * <li>The event is never fired from inside code triggered by a
056         *     synchronous event. Attempting to do so results in an {@link
057         *     java.lang.IllegalStateException}.
058         * <li>However, asynchronous event handlers may fire synchronous or
059         *     asynchronous events
060         * <li>The event may be fired multiple times simultaneously and in any
061         *     order.
062         * <li>Any newly registered or unregistered handler is ignored after an
063         *     event starts execution.
064         * <li>The handlers for this event may block for any length of time.
065         * <li>Some implementations may selectively declare a specific event use
066         *     as asynchronous. This behavior should be clearly defined.
067         * <li>Asynchronous calls are not calculated in the plugin timing system.
068         * </ul>
069         *
070         * @return false by default, true if the event fires asynchronously
071         */
072        public final boolean isAsynchronous() {
073            return async;
074        }
075    
076        public enum Result {
077    
078            /**
079             * Deny the event. Depending on the event, the action indicated by the
080             * event will either not take place or will be reverted. Some actions
081             * may not be denied.
082             */
083            DENY,
084            /**
085             * Neither deny nor allow the event. The server will proceed with its
086             * normal handling.
087             */
088            DEFAULT,
089            /**
090             * Allow / Force the event. The action indicated by the event will
091             * take place if possible, even if the server would not normally allow
092             * the action. Some actions may not be allowed.
093             */
094            ALLOW;
095        }
096    }