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.tapestry;
016
017 import org.apache.tapestry.ioc.AnnotationProvider;
018 import org.apache.tapestry.ioc.Messages;
019 import org.apache.tapestry.ioc.Resource;
020 import org.apache.tapestry.model.ComponentModel;
021 import org.apache.tapestry.runtime.Component;
022 import org.apache.tapestry.runtime.PageLifecycleListener;
023
024 import java.lang.annotation.Annotation;
025
026 /**
027 * Provides a component instance with the resources provided by the framework. In many circumstances, the resources
028 * object can be considered the component itself; in others, it is the {@link #getComponent() component property}, and
029 * instance of a class provided by the application developer (though transformed in many ways while being loaded) that
030 * is the true component. In reality, it is the combination of the resources object with the lifecycle instance.
031 */
032 public interface ComponentResources extends ComponentResourcesCommon
033 {
034 /**
035 * Returns the base resource for the component, which will represent the class's location within the classpath (this
036 * is used to resolve relative assets).
037 */
038 Resource getBaseResource();
039
040 /**
041 * Returns the component model object that defines the behavior of the component.
042 */
043 ComponentModel getComponentModel();
044
045 /**
046 * Returns the component this object provides resources for.
047 */
048 Component getComponent();
049
050 /**
051 * Returns the component which contains this component, or null for the root component. For mixins, this returns the
052 * componet to which the mixin is attached.
053 */
054 Component getContainer();
055
056 /**
057 * Returns the {@link ComponentResources} for the container, or null if the this is the root component (that has no
058 * container). As a special case, for a mixin, this returns the core component's resources.
059 */
060 ComponentResources getContainerResources();
061
062 /**
063 * Returns the {@link Messages} from the container, or null if this is the root component (with no container). As a
064 * special case, for a mixin, this return the core component's messages.
065 */
066 Messages getContainerMessages();
067
068 /**
069 * Returns the page that contains this component. Technically, the page itself is an internal object in Tapestry and
070 * this returns the root component of the actual page, but from an application developer point of view, this is the
071 * page.
072 */
073 Component getPage();
074
075 /**
076 * Returns an embedded component, given the component's id.
077 *
078 * @param embeddedId selects the embedded component (case is ignored)
079 * @throws IllegalArgumentException if this component does not contain a component with the given id
080 */
081
082 Component getEmbeddedComponent(String embeddedId);
083
084 /**
085 * Returns true if the named parameter is bound, false if not.
086 */
087 boolean isBound(String parameterName);
088
089 /**
090 * Obtains an annotation provided by a parameter.
091 *
092 * @param parameterName name of parameter to search for the annotation
093 * @param annotationType the type of annotation
094 * @return the annotation if found or null otherwise
095 */
096 <T extends Annotation> T getParameterAnnotation(String parameterName, Class<T> annotationType);
097
098 /**
099 * Indentifies all parameters that are not formal parameters and writes each as a attribute/value pair into the
100 * current element of the markup writer.
101 *
102 * @param writer to which {@link MarkupWriter#attributes(Object[]) attributes} will be written
103 */
104 void renderInformalParameters(MarkupWriter writer);
105
106 /**
107 * Returns the message catalog for this component.
108 */
109 Messages getMessages();
110
111 /**
112 * Returns the actual type of the bound parameter, or null if the parameter is not bound. This is primarily used
113 * with property bindings, and is used to determine the actual type of the property, rather than the type of
114 * parameter (remember that type coercion automatically occurs, which can mask significant differences between the
115 * parameter type and the bound property type).
116 *
117 * @param parameterName used to select the parameter (case is ignored)
118 * @return the type of the bound parameter, or null if the parameter is not bound
119 * @see Binding#getBindingType()
120 */
121 Class getBoundType(String parameterName);
122
123 /**
124 * Returns an annotation provider, used to obtain annotations related to the parameter.
125 *
126 * @param parameterName used to select the parameter (case is ignored)
127 * @return the annotation provider, or null if the parameter is not bound
128 */
129 AnnotationProvider getAnnotationProvider(String parameterName);
130
131 /**
132 * Used to access an informal parameter that's a Block.
133 *
134 * @param parameterName the name of the informal parameter (case is ignored)
135 * @return the informal Block parameter, or null if not bound
136 */
137 Block getBlockParameter(String parameterName);
138
139 /**
140 * Returns a previously stored render variable.
141 *
142 * @param name of the variable (case will be ignored)
143 * @return the variable's value
144 * @throws IllegalArgumentException if the name doesn't correspond to a stored value
145 */
146 Object getRenderVariable(String name);
147
148 /**
149 * Stores a render variable, accessible with the provided name.
150 *
151 * @param name of value to store
152 * @param value value to store (may not be null)
153 * @throws IllegalStateException if the component is not currently rendering
154 */
155 void storeRenderVariable(String name, Object value);
156
157 /**
158 * Adds a listener object that will be notified about page lifecycle events.
159 */
160 void addPageLifecycleListener(PageLifecycleListener listener);
161
162
163 /**
164 * Creates a component action request link as a callback for this component. The event type and context (as well as
165 * the page name and nested component id) will be encoded into a URL. A request for the URL will {@linkplain
166 * #triggerEvent(String, Object[], ComponentEventCallback)} trigger} the named event on the component.
167 *
168 * @param eventType the type of event to be triggered. Event types should be Java identifiers (contain only
169 * letters, numbers and the underscore).
170 * @param forForm if true, the link will be used as the eventType for an HTML form submission, which may affect
171 * what information is encoded into the link
172 * @param context additional objects to be encoded into the path portion of the link; each is converted to a
173 * string and URI encoded
174 * @return link object for the callback
175 */
176 Link createActionLink(String eventType, boolean forForm, Object... context);
177
178 /**
179 * Creates a render request link to a specific page.
180 *
181 * @param pageName the logical name of the page to link to
182 * @param override if true, the context is used even if empty (normally, the target page is allowed to passivate,
183 * providing a context, when the provided context is empty)
184 * @param context the activation context for the page. If omitted, the activation context is obtained from the
185 * target paget
186 */
187 Link createPageLink(String pageName, boolean override, Object... context);
188
189 /**
190 * Discards all persistent field changes for the page containing the component. Changes are eliminated from
191 * persistent storage (such as the {@link org.apache.tapestry.services.Session}) which will take effect in the
192 * <em>next</em> request (the attached page instance is not affected).
193 */
194 void discardPersistentFieldChanges();
195
196 /**
197 * Returns the name of element that represents the component in its template, or null if not known.
198 *
199 * @return the element name or null
200 */
201 String getElementName();
202 }