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