001    // Copyright 2006, 2007, 2008, 2010 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    import org.apache.tapestry5.ComponentResourcesCommon;
018    import org.apache.tapestry5.EventContext;
019    
020    /**
021     * An event that may originate in application logic, or as a result of a client interaction (a GET or POST from the
022     * client).
023     * 
024     * @see ComponentResourcesCommon#triggerEvent(String, Object[], org.apache.tapestry5.ComponentEventCallback)
025     * @see org.apache.tapestry5.ComponentEventCallback
026     */
027    public interface ComponentEvent extends Event
028    {
029        /**
030         * Returns true if the event matches the provided criteria and the event has not yet been aborted.
031         * 
032         * @param eventType
033         *            the type of event (case insensitive match)
034         * @param componentId
035         *            component is to match against (case insensitive), or the empty string
036         * @param parameterCount
037         *            minimum number of context values
038         * @return true if the event matches (and has not yet been aborted)
039         */
040        boolean matches(String eventType, String componentId, int parameterCount);
041    
042        /**
043         * Coerces a context value to a particular type. The context is an array of objects; typically it is an array of
044         * strings of extra path information encoded into the action URL.
045         * 
046         * @param index
047         *            the index of the context value
048         * @param desiredTypeName
049         *            the desired type
050         * @return the coerced value (a wrapper type if the desired type is a primitive)
051         */
052        Object coerceContext(int index, String desiredTypeName);
053    
054        /**
055         * Returns the underlying {@link org.apache.tapestry5.EventContext} as a (possibly empty) array.
056         */
057        Object[] getContext();
058    
059        /**
060         * Returns the underlying event context.
061         */
062        EventContext getEventContext();
063    }