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