    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.internal.structure;
    016
    017    import org.apache.tapestry5.Binding;
    018    import org.apache.tapestry5.Block;
    019    import org.apache.tapestry5.ComponentResources;
    020    import org.apache.tapestry5.ComponentResourcesCommon;
    021    import org.apache.tapestry5.internal.InternalComponentResources;
    022    import org.apache.tapestry5.internal.InternalComponentResourcesCommon;
    023    import org.apache.tapestry5.internal.services.Instantiator;
    024    import org.apache.tapestry5.ioc.Location;
    025    import org.apache.tapestry5.runtime.Component;
    026    import org.apache.tapestry5.runtime.ComponentEvent;
    027    import org.apache.tapestry5.runtime.RenderCommand;
    028    import org.apache.tapestry5.runtime.RenderQueue;
    029    import org.slf4j.Logger;
    030
    031    /**
    032     * Defines an element of a page that is a component elements that are, in fact, components (rather than just static
    033     * markup).
    034     */
    035    public interface ComponentPageElement extends ComponentResourcesCommon, InternalComponentResourcesCommon, RenderCommand, BodyPageElement
    036    {
    037        /**
    038         * Returns the core component associated with this page element (as opposed to any mixins attached to the
    039         * component).
    040         */
    041        Component getComponent();
    042
    043        /**
    044         * Returns the resources associated with the core component.
    045         */
    046        InternalComponentResources getComponentResources();
    047
    048        /**
    049         * Returns the page which contains this component.
    050         */
    051        Page getContainingPage();
    052
    053        /**
    054         * Containing component (or null for the root component of a page).
    055         */
    056        ComponentPageElement getContainerElement();
    057
    058        /**
    059         * Used during the construction of a page. Adds a page element as part of the template for this page element. A page
    060         * element will eventually render by sequentially rendering these elements. A page elements template is really just
    061         * the outermost portions of the component's template ... where a template contains elements that are all
    062         * components, those components will receive portions of the template as their body.
    063         */
    064        void addToTemplate(RenderCommand element);
    065
    066        /**
    067         * Used during the contruction of a page to add a non-anonymous Block to the component.
    068         *
    069         * @see ComponentResourcesCommon#getBlock(String)
    070         */
    071        void addBlock(String blockId, Block block);
    072
    073        /**
    074         * Adds a mixin.
    075         *
    076         * @param mixinId      a unique id for the mixin, the last term of the mixin's class name
    077         * @param instantiator used to instantiate an instance of the mixin
    078         * @param order        Ordering strings used to determine the order of mixin execution.
    079         */
    080        void addMixin(String mixinId, Instantiator instantiator, String... order);
    081
    082        /**
    083         * @param mixinId       id of previously added mixin
    084         * @param parameterName simple (unqualified) name of parameter
    085         * @param binding       binding for parameter
    086         * @since 5.1.0.0
    087         */
    088        void bindMixinParameter(String mixinId, String parameterName, Binding binding);
    089
    090        /**
    091         * Retrieves a component page element by its id. The search is caseless.
    092         *
    093         * @param id used to locate the element
    094         * @return the page element
    095         * @throws IllegalArgumentException if no component exists with the given id
    096         */
    097        ComponentPageElement getEmbeddedElement(String id);
    098
    099        /**
    100         * Returns the {@link org.apache.tapestry5.ComponentResources} for a mixin attached to this component element. Mixin
    101         * ids are the simple names of the mixin class.
    102         *
    103         * @param mixinId the mixin id (case insensitive)
    104         * @return the resources for the component
    105         * @throws IllegalArgumentException if no mixin with the given id exists
    106         */
    107        ComponentResources getMixinResources(String mixinId);
    108
    109        /**
    110         * Invoked when the component should render its body.
    111         */
    112        void enqueueBeforeRenderBody(RenderQueue queue);
    113
    114        /**
    115         * Asks each mixin and component to {@link Component#dispatchComponentEvent(ComponentEvent)}, returning true if any
    116         * handler was found.
    117         *
    118         * @param event to be handled
    119         * @return true if a handler was found
    120         */
    121        boolean dispatchEvent(ComponentEvent event);
    122
    123        /**
    124         * Creates a new child component of the invoked component.  The new element will be added as an embedded element of
    125         * its container.
    126         *
    127         * @param id           simple id of the new component
    128         * @param nestedId
    129         * @param completeId
    130         * @param elementName  name of the component's element in its container's template
    131         * @param instantiator used to create a component instance, and access the component's model
    132         * @param location     location of the element within its container's template @return the new component
    133         */
    134        ComponentPageElement newChild(String id, String nestedId, String completeId, String elementName,
    135                                      Instantiator instantiator,
    136                                      Location location);
    137
    138        /**
    139         * Returns a logger used to for logging event dispatch and event method invocation.
    140         */
    141        Logger getEventLogger();
    142    }