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
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.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 */
035public 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}