    001    // Copyright 2006, 2007, 2008, 2009, 2011 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;
    016
    017    import org.apache.tapestry5.ioc.Locatable;
    018    import org.apache.tapestry5.services.pageload.ComponentResourceSelector;
    019    import org.slf4j.Logger;
    020
    021    import java.util.Locale;
    022
    023    /**
    024     * Operations shared by the public {@link org.apache.tapestry5.ComponentResources} interface and
    025     * {@link org.apache.tapestry5.internal.structure.ComponentPageElement} interface (on the internal side).
    026     */
    027    @SuppressWarnings(
    028    { "JavaDoc" })
    029    public interface ComponentResourcesCommon extends Locatable
    030    {
    031        /**
    032         * Returns the simple (or local) id of the component. The id will be unique within the component's immediate
    033         * container. For a page's root component, the value null is returned.
    034         */
    035        String getId();
    036
    037        /**
    038         * Return a string consisting the concatinated ids of all containing components, separated by periods. In addition,
    039         * nested ids are always all lower case. I.e., "foo.bar.baz". Returns null for the root component of a page.
    040         */
    041        String getNestedId();
    042
    043        /**
    044         * Returns a string consisting of the logical name of the containing page, and the {@link #getNestedId() nested id}
    045         * of this component, separated by a colon. I.e., "MyPage:foo.bar.baz". For a page, returns just the page's name.
    046         * <p/>
    047         * This value is often used to obtain an equivalent component instance in a later request.
    048         *
    049         * @see org.apache.tapestry5.services.ComponentSource#getComponent(String)
    050         */
    051        String getCompleteId();
    052
    053        /**
    054         * A convienience for invoking {@link #triggerContextEvent(String, EventContext , ComponentEventCallback)}. Wraps
    055         * the context values into an {@link org.apache.tapestry5.EventContext}.
    056         *
    057         * @param eventType
    058         *            event type (as determined from the request, or otherwise by design)
    059         * @param contextValues
    060         *            Values that may be provided to the event handler method as method parameters, or null if no
    061         *            context values are available
    062         * @param callback
    063         *            the handler to be informed of the result, or null if the event is a notification that does
    064         *            not support return values from event handler methods (the value true is allowed even if the
    065         *            handler is null).
    066         * @return true if any event handler was invoked (even if no event handler method returns a non-null value)
    067         * @throws org.apache.tapestry5.runtime.ComponentEventException
    068         *             if an event handler method throws a checked or unchecked exception
    069         * @see org.apache.tapestry5.internal.transform.OnEventWorker
    070         * @see org.apache.tapestry5.annotations.OnEvent
    071         */
    072        boolean triggerEvent(String eventType, Object[] contextValues, ComponentEventCallback callback);
    073
    074        /**
    075         * Triggers a component event. A search for an event handling method will occur, first in the component, then its
    076         * container, and so on. When a matching event handler method is located, it is invoked. If the method returns a
    077         * value, the value is passed to the callback (if callback is null, then it is an error for a method to return a
    078         * non-null value).
    079         * <p/>
    080         * Resolution of event type to event handler methods is case insensitive.
    081         *
    082         * @param eventType
    083         *            event type (as determined from the request, or otherwise by design)
    084         * @param context
    085         *            the context (as extracted from the request, or provided by the triggering component); these
    086         *            values may be provided to event handler methods via their parameters (may not be null)
    087         * @param callback
    088         *            the handler to be informed of the result, or null if the event is a notification that does not
    089         *            support return values from event handler methods (the value true is allowed even if the handler
    090         *            is null).
    091         * @return true if any event handler was invoked (even if no event handler method returns a non-null value)
    092         * @throws org.apache.tapestry5.runtime.ComponentEventException
    093         *             if an event handler method throws a checked or unchecked exception
    094         * @see org.apache.tapestry5.internal.transform.OnEventWorker
    095         * @see org.apache.tapestry5.annotations.OnEvent
    096         */
    097        boolean triggerContextEvent(String eventType, EventContext context, ComponentEventCallback callback);
    098
    099        /**
    100         * Returns true if the component is currently rendering, false otherwise. This is most often used to determine if
    101         * parameter values should be cached.
    102         */
    103        boolean isRendering();
    104
    105        /**
    106         * Returns the log instance associated with the component (which is based on the component or mixin's class name).
    107         *
    108         * @see org.apache.tapestry5.model.ComponentModel#getLogger()
    109         */
    110        Logger getLogger();
    111
    112        /**
    113         * Returns the locale for the page containing this component.
    114         *
    115         * @see #getResourceSelector()
    116         */
    117        Locale getLocale();
    118
    119        /**
    120         * Returns the selector used when constructing the component and its containing page.
    121         *
    122         * @since 5.3
    123         */
    124        ComponentResourceSelector getResourceSelector();
    125
    126        /**
    127         * Returns the name of element that represents the component in its template, or the provided default element name
    128         * if the element was a component type (in the Tapestry namespace).
    129         *
    130         * @param defaultElementName
    131         *            element name to return if the element name is not known (may be null)
    132         * @return the element name
    133         */
    134        String getElementName(String defaultElementName);
    135
    136        /**
    137         * Returns a block from the component's template, referenced by its id.
    138         *
    139         * @param blockId
    140         *            the id of the block (case insensitive)
    141         * @return the identified Block
    142         * @throws BlockNotFoundException
    143         *             if no block with the given id exists
    144         * @see #findBlock(String)
    145         */
    146        Block getBlock(String blockId);
    147
    148        /**
    149         * As with {@link #getBlock(String)}, but returns null if the block is not found.
    150         *
    151         * @param blockId
    152         *            the id of the block (case insensitive)
    153         * @return the block, or null
    154         */
    155        Block findBlock(String blockId);
    156
    157        /**
    158         * Returns the <em>logical</em> name of the page containing this component. This is the short name (it often appears
    159         * in URLs)
    160         *
    161         * @return the logical name of the page which contains this component
    162         */
    163        String getPageName();
    164
    165        /**
    166         * Returns true if the element has a body and false otherwise. Only components may have a body; pages and mixins
    167         * will return false.
    168         */
    169        boolean hasBody();
    170
    171        /**
    172         * Returns the body of this component as a (possibly empty) block. When invoked on a mixin, returns the containing
    173         * component's body.
    174         */
    175        Block getBody();
    176
    177        /**
    178         * Creates a component event request link as a callback for this component. The event type and context (as well as
    179         * the page name and nested component id) will be encoded into a URL. A request for the URL will
    180         * {@linkplain #triggerEvent(String, Object[], org.apache.tapestry5.ComponentEventCallback)} trigger} the named
    181         * event on the
    182         * component.
    183         *
    184         * @param eventType
    185         *            the type of event to be triggered. Event types should be Java identifiers (contain only
    186         *            letters, numbers and the underscore).
    187         * @param context
    188         *            additional objects to be encoded into the path portion of the link; each is converted to a
    189         *            string and URI encoded
    190         * @return link object for the callback
    191         */
    192        Link createEventLink(String eventType, Object... context);
    193
    194        /**
    195         * Creates a component event request link as a callback for this component. The event type and context (as well as
    196         * the page name and nested component id) will be encoded into a URL. A request for the URL will
    197         * {@linkplain #triggerEvent(String, Object[], org.apache.tapestry5.ComponentEventCallback)} trigger} the named
    198         * event on the
    199         * component.
    200         *
    201         * @param eventType
    202         *            the type of event to be triggered. Event types should be Java identifiers (contain only
    203         *            letters, numbers and the underscore).
    204         * @param forForm
    205         *            if true, the link will be used as the eventType for an HTML form submission, which may affect
    206         *            what information is encoded into the link
    207         * @param context
    208         *            additional objects to be encoded into the path portion of the link; each is converted to a
    209         *            string and URI encoded
    210         * @return link object for the callback
    211         * @deprecated Use {@link #createEventLink(String, Object[])} instead
    212         */
    213        Link createActionLink(String eventType, boolean forForm, Object... context);
    214
    215        /**
    216         * Creates a component event request link as a callback for this component. The event type and context (as well as
    217         * the page name and nested component id) will be encoded into a URL. A request for the URL will
    218         * {@linkplain #triggerEvent(String, Object[], org.apache.tapestry5.ComponentEventCallback)} trigger} the named
    219         * event on the
    220         * component. This is only used for form submission events, as extra data may be encoded in the form as hidden
    221         * fields.
    222         *
    223         * @param eventType
    224         *            the type of event to be triggered. Event types should be Java identifiers (contain only
    225         *            letters, numbers and the underscore).
    226         * @param context
    227         *            additional objects to be encoded into the path portion of the link; each is converted to a
    228         *            string and URI encoded
    229         * @return link object for the callback
    230         */
    231        Link createFormEventLink(String eventType, Object... context);
    232
    233        /**
    234         * Creates a page render request link to render a specific page.
    235         *
    236         * @param pageName
    237         *            the logical name of the page to link to
    238         * @param override
    239         *            if true, the context is used even if empty (normally, the target page is allowed to passivate,
    240         *            providing a context, when the provided context is empty)
    241         * @param context
    242         *            the activation context for the page. If omitted, the activation context is obtained from the
    243         *            target page
    244         * @return link for a render request to the targetted page
    245         * @deprecated Use {@link org.apache.tapestry5.services.PageRenderLinkSource#createPageRenderLink(String)} or
    246         *             {@link org.apache.tapestry5.services.PageRenderLinkSource#createPageRenderLinkWithContext(String, Object[])}
    247         *             instead
    248         */
    249        Link createPageLink(String pageName, boolean override, Object... context);
    250
    251        /**
    252         * Creates a page render request link to render a specific page. Using a page class, rather than a page name, is
    253         * more refactoring safe (in the even the page is renamed or moved).
    254         *
    255         * @param pageClass
    256         *            identifies the page to link to
    257         * @param override
    258         *            if true, the context is used even if empty (normally, the target page is allowed to passivate,
    259         *            providing a context, when the provided context is empty)
    260         * @param context
    261         *            the activation context for the page. If omitted, the activation context is obtained from the
    262         *            target page
    263         * @return link for a render request to the targetted page
    264         * @deprecated Use {@link org.apache.tapestry5.services.PageRenderLinkSource#createPageRenderLink(Class)} or
    265         *             {@link org.apache.tapestry5.services.PageRenderLinkSource#createPageRenderLinkWithContext(Class, Object[])}
    266         *             instead
    267         */
    268        Link createPageLink(Class pageClass, boolean override, Object... context);
    269    }