001    // Copyright 2007, 2008 The Apache Software Foundation
002    //
003    // Licensed under the Apache License, Version 2.0 (the "License");
004    // you may not use this file except in compliance with the License.
005    // You may obtain a copy of the License at
006    //
007    //     http://www.apache.org/licenses/LICENSE-2.0
008    //
009    // Unless required by applicable law or agreed to in writing, software
010    // distributed under the License is distributed on an "AS IS" BASIS,
011    // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
012    // See the License for the specific language governing permissions and
013    // limitations under the License.
014    
015    package org.apache.tapestry5.runtime;
016    
017    /**
018     * The core methods related to event handling. Events used in this way exist to gather data from user code, by invoking
019     * user methods and capturing the response. Return values from methods, if non-null, are passed to a {@link
020     * org.apache.tapestry5.ComponentEventCallback}. The {@link ComponentEvent} subinterface extends this by providing
021     * access to a context, or set of information related to the event, along with additional data used, at runtime, to
022     * match events to user code methods.
023     */
024    public interface Event
025    {
026        /**
027         * Returns true if the event has been aborted (meaning that the return value from some event handler method was
028         * accepted, and processing of the event was terminated).
029         *
030         * @return true if no further event handler methods should be invoked
031         */
032        boolean isAborted();
033    
034        /**
035         * Invoke to identify, to the event, what component and method is being acted upon (used for some kinds of exception
036         * reporting).
037         *
038         * @param methodDescription describes the location (i.e. file name, method name and line number) of the method
039         */
040        void setMethodDescription(String methodDescription);
041    
042        /**
043         * Stores a result for the event. Storing a non-null result value may abort the event (at the discretion of the
044         * {@link org.apache.tapestry5.ComponentEventCallback}).
045         *
046         * @param result the result obtained from a method invocations
047         * @return true if the event is now aborted
048         */
049        boolean storeResult(Object result);
050    }