    001// Licensed under the Apache License, Version 2.0 (the "License");
    002// you may not use this file except in compliance with the License.
    003// You may obtain a copy of the License at
    004//
    005// http://www.apache.org/licenses/LICENSE-2.0
    006//
    007// Unless required by applicable law or agreed to in writing, software
    008// distributed under the License is distributed on an "AS IS" BASIS,
    009// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
    010// See the License for the specific language governing permissions and
    011// limitations under the License.
    012
    013package org.apache.tapestry5;
    014
    015import org.apache.tapestry5.commons.Locatable;
    016import org.apache.tapestry5.http.Link;
    017import org.apache.tapestry5.services.pageload.ComponentResourceSelector;
    018import org.slf4j.Logger;
    019
    020import java.util.Locale;
    021
    022/**
    023 * Operations shared by the public {@link org.apache.tapestry5.ComponentResources} interface and
    024 * {@link org.apache.tapestry5.internal.structure.ComponentPageElement} interface (on the internal side).
    025 */
    026@SuppressWarnings(
    027{ "JavaDoc" })
    028public interface ComponentResourcesCommon extends Locatable
    029{
    030    /**
    031     * Returns the simple (or local) id of the component. The id will be unique within the component's immediate
    032     * container. For a page's root component, the value null is returned.
    033     */
    034    String getId();
    035
    036    /**
    037     * Return a string consisting the concatenated ids of all containing components, separated by periods. In addition,
    038     * nested ids are always all lower case. I.e., "foo.bar.baz". Returns null for the root component of a page.
    039     */
    040    String getNestedId();
    041
    042    /**
    043     * Returns a string consisting of the logical name of the containing page, and the {@link #getNestedId() nested id}
    044     * of this component, separated by a colon. I.e., "MyPage:foo.bar.baz". For a page, returns just the page's name.
    045     *
    046     * This value is often used to obtain an equivalent component instance in a later request.
    047     *
    048     * @see org.apache.tapestry5.services.ComponentSource#getComponent(String)
    049     */
    050    String getCompleteId();
    051
    052    /**
    053     * A convenience method for invoking {@link #triggerContextEvent(String, EventContext , ComponentEventCallback)}. Wraps
    054     * the context values into an {@link org.apache.tapestry5.EventContext}.
    055     *
    056     * @param eventType
    057     *            event type (as determined from the request, or otherwise by design)
    058     * @param contextValues
    059     *            Values that may be provided to the event handler method as method parameters, or null if no
    060     *            context values are available
    061     * @param callback
    062     *            the handler to be informed of the result, or null if the event is a notification that does
    063     *            not support return values from event handler methods (the value true is allowed even if the
    064     *            handler is null).
    065     * @return true if any event handler was invoked (even if no event handler method returns a non-null value)
    066     * @throws org.apache.tapestry5.runtime.ComponentEventException
    067     *             if an event handler method throws a checked or unchecked exception
    068     * @see org.apache.tapestry5.internal.transform.OnEventWorker
    069     * @see org.apache.tapestry5.annotations.OnEvent
    070     */
    071    boolean triggerEvent(String eventType, Object[] contextValues, ComponentEventCallback callback);
    072
    073    /**
    074     * Triggers a component event. A search for an event handling method will occur, first in the component, then its
    075     * container, and so on. When a matching event handler method is located, it is invoked. If the method returns a
    076     * value, the value is passed to the callback (if callback is null, then it is an error for a method to return a
    077     * non-null value).
    078     *
    079     * Resolution of event type to event handler methods is case insensitive.
    080     *
    081     * @param eventType
    082     *            event type (as determined from the request, or otherwise by design)
    083     * @param context
    084     *            the context (as extracted from the request, or provided by the triggering component); these
    085     *            values may be provided to event handler methods via their parameters (may not be null)
    086     * @param callback
    087     *            the handler to be informed of the result, or null if the event is a notification that does not
    088     *            support return values from event handler methods (the value true is allowed even if the handler
    089     *            is null).
    090     * @return true if any event handler was invoked (even if no event handler method returns a non-null value)
    091     * @throws org.apache.tapestry5.runtime.ComponentEventException
    092     *             if an event handler method throws a checked or unchecked exception
    093     * @see org.apache.tapestry5.internal.transform.OnEventWorker
    094     * @see org.apache.tapestry5.annotations.OnEvent
    095     */
    096    boolean triggerContextEvent(String eventType, EventContext context, ComponentEventCallback callback);
    097
    098    /**
    099     * Returns true if the component is currently rendering, false otherwise. This is most often used to determine if
    100     * parameter values should be cached.
    101     */
    102    boolean isRendering();
    103
    104    /**
    105     * Returns the log instance associated with the component (which is based on the component or mixin's class name).
    106     *
    107     * @see org.apache.tapestry5.model.ComponentModel#getLogger()
    108     */
    109    Logger getLogger();
    110
    111    /**
    112     * Returns the locale for the page containing this component.
    113     *
    114     * @see #getResourceSelector()
    115     */
    116    Locale getLocale();
    117
    118    /**
    119     * Returns the selector used when constructing the component and its containing page.
    120     *
    121     * @since 5.3
    122     */
    123    ComponentResourceSelector getResourceSelector();
    124
    125    /**
    126     * Returns the name of element that represents the component in its template, or the provided default element name
    127     * if the element was a component type (in the Tapestry namespace).
    128     *
    129     * @param defaultElementName
    130     *            element name to return if the element name is not known (may be null)
    131     * @return the element name
    132     */
    133    String getElementName(String defaultElementName);
    134
    135    /**
    136     * Returns a block from the component's template, referenced by its id.
    137     *
    138     * @param blockId
    139     *            the id of the block (case insensitive)
    140     * @return the identified Block
    141     * @throws BlockNotFoundException
    142     *             if no block with the given id exists
    143     * @see #findBlock(String)
    144     */
    145    Block getBlock(String blockId);
    146
    147    /**
    148     * As with {@link #getBlock(String)}, but returns null if the block is not found.
    149     *
    150     * @param blockId
    151     *            the id of the block (case insensitive)
    152     * @return the block, or null
    153     */
    154    Block findBlock(String blockId);
    155
    156    /**
    157     * Returns the <em>logical</em> name of the page containing this component. This is the short name (it often appears
    158     * in URLs)
    159     *
    160     * @return the logical name of the page which contains this component
    161     */
    162    String getPageName();
    163
    164    /**
    165     * Returns true if the element has a body and false otherwise. Only components may have a body; pages and mixins
    166     * will return false.
    167     */
    168    boolean hasBody();
    169
    170    /**
    171     * Returns the body of this component as a (possibly empty) block. When invoked on a mixin, returns the containing
    172     * component's body.
    173     */
    174    Block getBody();
    175
    176    /**
    177     * Creates a component event request link as a callback for this component. The event type and context (as well as
    178     * the page name and nested component id) will be encoded into a URL. A request for the URL will
    179     * {@linkplain #triggerEvent(String, Object[], org.apache.tapestry5.ComponentEventCallback)} trigger} the named
    180     * event on the
    181     * component.
    182     *
    183     * @param eventType
    184     *            the type of event to be triggered. Event types should be Java identifiers (contain only
    185     *            letters, numbers and the underscore).
    186     * @param context
    187     *            additional objects to be encoded into the path portion of the link; each is converted to a
    188     *            string and URI encoded
    189     * @return link object for the callback
    190     */
    191    Link createEventLink(String eventType, Object... context);
    192
    193    /**
    194     * Creates a component event request link as a callback for this component. The event type and context (as well as
    195     * the page name and nested component id) will be encoded into a URL. A request for the URL will
    196     * {@linkplain #triggerEvent(String, Object[], org.apache.tapestry5.ComponentEventCallback)} trigger} the named
    197     * event on the
    198     * component. This is only used for form submission events, as extra data may be encoded in the form as hidden
    199     * fields.
    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 context
    205     *            additional objects to be encoded into the path portion of the link; each is converted to a
    206     *            string and URI encoded
    207     * @return link object for the callback
    208     */
    209    Link createFormEventLink(String eventType, Object... context);
    210}