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}