    001    // Copyright 2006, 2007, 2008, 2012 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.AnnotationProvider;
    018    import org.apache.tapestry5.ioc.Messages;
    019    import org.apache.tapestry5.ioc.Resource;
    020    import org.apache.tapestry5.model.ComponentModel;
    021    import org.apache.tapestry5.runtime.Component;
    022    import org.apache.tapestry5.runtime.PageLifecycleCallbackHub;
    023    import org.apache.tapestry5.runtime.PageLifecycleListener;
    024
    025    import java.lang.annotation.Annotation;
    026    import java.util.List;
    027
    028    /**
    029     * Provides a component instance with the resources provided by the framework. In many circumstances, the resources
    030     * object can be considered the component itself; in others, it is the {@linkplain #getComponent() component property},
    031     * an instance of a class provided by the application developer (though transformed in many ways while being loaded)
    032     * that is the true component. In reality, it is the combination of the resources object with the user class instance
    033     * that forms the components; neither is useful without the other.
    034     */
    035    public interface ComponentResources extends ComponentResourcesCommon
    036    {
    037        /**
    038         * Returns the base resource for the component, which will represent the class's location within the classpath (this
    039         * is used to resolve relative assets).
    040         */
    041        Resource getBaseResource();
    042
    043        /**
    044         * Returns the component model object that defines the behavior of the component.
    045         */
    046        ComponentModel getComponentModel();
    047
    048        /**
    049         * Returns the component this object provides resources for.
    050         */
    051        Component getComponent();
    052
    053        /**
    054         * Returns the component which contains this component, or null for the root component. For mixins, this returns the
    055         * componet to which the mixin is attached.
    056         */
    057        Component getContainer();
    058
    059        /**
    060         * Returns the {@link ComponentResources} for the container, or null if the this is the root component (that has no
    061         * container). As a special case, for a mixin, this returns the core component's resources.
    062         */
    063        ComponentResources getContainerResources();
    064
    065        /**
    066         * Returns the {@link Messages} from the container, or null if this is the root component (with no container). As a
    067         * special case, for a mixin, this return the core component's messages.
    068         */
    069        Messages getContainerMessages();
    070
    071        /**
    072         * Returns the page that contains this component. Technically, the page itself is an internal object in Tapestry and
    073         * this returns the root component of the actual page, but from an application developer point of view, this is the
    074         * page.
    075         */
    076        Component getPage();
    077
    078        /**
    079         * Returns an embedded component, given the component's id.
    080         *
    081         * @param embeddedId
    082         *         selects the embedded component (case is ignored)
    083         * @throws org.apache.tapestry5.ioc.util.UnknownValueException
    084         *         if this component does not contain a component with the given id
    085         */
    086
    087        Component getEmbeddedComponent(String embeddedId);
    088
    089        /**
    090         * Returns true if the named parameter is bound, false if not.
    091         */
    092        boolean isBound(String parameterName);
    093
    094        /**
    095         * Obtains an annotation provided by a parameter.
    096         *
    097         * @param parameterName
    098         *         name of parameter to search for the annotation
    099         * @param annotationType
    100         *         the type of annotation
    101         * @return the annotation if found or null otherwise
    102         */
    103        <T extends Annotation> T getParameterAnnotation(String parameterName, Class<T> annotationType);
    104
    105        /**
    106         * Indentifies all parameters that are not formal parameters and writes each as a attribute/value pair into the
    107         * current element of the markup writer.
    108         *
    109         * @param writer
    110         *         to which {@link MarkupWriter#attributes(Object[]) attributes} will be written
    111         */
    112        void renderInformalParameters(MarkupWriter writer);
    113
    114        /**
    115         * Returns the message catalog for this component.
    116         */
    117        Messages getMessages();
    118
    119        /**
    120         * Returns the actual type of the bound parameter, or null if the parameter is not bound. This is primarily used
    121         * with property bindings, and is used to determine the actual type of the property, rather than the type of
    122         * parameter (remember that type coercion automatically occurs, which can mask significant differences between the
    123         * parameter type and the bound property type).
    124         *
    125         * @param parameterName
    126         *         used to select the parameter (case is ignored)
    127         * @return the type of the bound parameter, or null if the parameter is not bound
    128         * @see Binding#getBindingType()
    129         */
    130        Class getBoundType(String parameterName);
    131
    132        /**
    133         * Returns an annotation provider, used to obtain annotations related to the parameter.
    134         *
    135         * @param parameterName
    136         *         used to select the parameter (case is ignored)
    137         * @return the annotation provider, or null if the parameter is not bound
    138         */
    139        AnnotationProvider getAnnotationProvider(String parameterName);
    140
    141        /**
    142         * Used to access an informal parameter that's a Block.
    143         *
    144         * @param parameterName
    145         *         the name of the informal parameter (case is ignored)
    146         * @return the informal Block parameter, or null if not bound
    147         */
    148        Block getBlockParameter(String parameterName);
    149
    150        /**
    151         * Returns a previously stored render variable.
    152         *
    153         * @param name
    154         *         of the variable (case will be ignored)
    155         * @return the variable's value
    156         * @throws IllegalArgumentException
    157         *         if the name doesn't correspond to a stored value
    158         */
    159        Object getRenderVariable(String name);
    160
    161        /**
    162         * Stores a render variable, accessible with the provided name.
    163         *
    164         * @param name
    165         *         of value to store
    166         * @param value
    167         *         value to store (may not be null)
    168         * @throws IllegalStateException
    169         *         if the component is not currently rendering
    170         */
    171        void storeRenderVariable(String name, Object value);
    172
    173        /**
    174         * Adds a listener object that will be notified about page lifecycle events.
    175         *
    176         * @deprecated In 5.3.4, use {@link #getPageLifecycleCallbackHub()} instead
    177         */
    178        void addPageLifecycleListener(PageLifecycleListener listener);
    179
    180        /**
    181         * Provides access to an object that can be used to register callbacks for page lifecycle events.
    182         *
    183         * @return the hub
    184         * @since 5.3.4
    185         */
    186        PageLifecycleCallbackHub getPageLifecycleCallbackHub();
    187
    188        /**
    189         * Removes a previously added listener.
    190         *
    191         * @since 5.2.0
    192         * @deprecated in 5.3.4, not necessary with {@link PageLifecycleCallbackHub#addPageLoadedCallback(Runnable)}.
    193         */
    194        void removePageLifecycleListener(PageLifecycleListener listener);
    195
    196        /**
    197         * Discards all persistent field changes for the page containing the component. Changes are eliminated from
    198         * persistent storage (such as the {@link org.apache.tapestry5.services.Session}) which will take effect in the
    199         * <em>next</em> request (the attached page instance is not affected).
    200         */
    201        void discardPersistentFieldChanges();
    202
    203        /**
    204         * Returns the name of element that represents the component in its template, or null if not known.
    205         *
    206         * @return the element name or null
    207         */
    208        String getElementName();
    209
    210        /**
    211         * Returns a list of the names of any informal parameters bound to this component.
    212         *
    213         * @return the name sorted alphabetically
    214         * @see org.apache.tapestry5.annotations.SupportsInformalParameters
    215         */
    216        List<String> getInformalParameterNames();
    217
    218        /**
    219         * Reads an informal parameter and {@linkplain org.apache.tapestry5.ioc.services.TypeCoercer coercers} the bound
    220         * value to the indicated type.
    221         *
    222         * @param name
    223         *         name of informal parameter
    224         * @param type
    225         *         output value type
    226         * @return instance of type
    227         */
    228        <T> T getInformalParameter(String name, Class<T> type);
    229
    230        /**
    231         * Returns true if these resources represent a mixin to another component. The component is the
    232         * {@linkplain #getContainerResources() container} of this resources.
    233         *
    234         * @since 5.2.0
    235         */
    236        boolean isMixin();
    237    }