    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
    015package 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 */
    024public 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}