    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    }