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 }