001 // Copyright 2006, 2007, 2008, 2009, 2011 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.Locatable;
018 import org.apache.tapestry5.services.pageload.ComponentResourceSelector;
019 import org.slf4j.Logger;
020
021 import java.util.Locale;
022
023 /**
024 * Operations shared by the public {@link org.apache.tapestry5.ComponentResources} interface and
025 * {@link org.apache.tapestry5.internal.structure.ComponentPageElement} interface (on the internal side).
026 */
027 @SuppressWarnings(
028 { "JavaDoc" })
029 public interface ComponentResourcesCommon extends Locatable
030 {
031 /**
032 * Returns the simple (or local) id of the component. The id will be unique within the component's immediate
033 * container. For a page's root component, the value null is returned.
034 */
035 String getId();
036
037 /**
038 * Return a string consisting the concatinated ids of all containing components, separated by periods. In addition,
039 * nested ids are always all lower case. I.e., "foo.bar.baz". Returns null for the root component of a page.
040 */
041 String getNestedId();
042
043 /**
044 * Returns a string consisting of the logical name of the containing page, and the {@link #getNestedId() nested id}
045 * of this component, separated by a colon. I.e., "MyPage:foo.bar.baz". For a page, returns just the page's name.
046 * <p/>
047 * This value is often used to obtain an equivalent component instance in a later request.
048 *
049 * @see org.apache.tapestry5.services.ComponentSource#getComponent(String)
050 */
051 String getCompleteId();
052
053 /**
054 * A convienience for invoking {@link #triggerContextEvent(String, EventContext , ComponentEventCallback)}. Wraps
055 * the context values into an {@link org.apache.tapestry5.EventContext}.
056 *
057 * @param eventType
058 * event type (as determined from the request, or otherwise by design)
059 * @param contextValues
060 * Values that may be provided to the event handler method as method parameters, or null if no
061 * context values are available
062 * @param callback
063 * the handler to be informed of the result, or null if the event is a notification that does
064 * not support return values from event handler methods (the value true is allowed even if the
065 * handler is null).
066 * @return true if any event handler was invoked (even if no event handler method returns a non-null value)
067 * @throws org.apache.tapestry5.runtime.ComponentEventException
068 * if an event handler method throws a checked or unchecked exception
069 * @see org.apache.tapestry5.internal.transform.OnEventWorker
070 * @see org.apache.tapestry5.annotations.OnEvent
071 */
072 boolean triggerEvent(String eventType, Object[] contextValues, ComponentEventCallback callback);
073
074 /**
075 * Triggers a component event. A search for an event handling method will occur, first in the component, then its
076 * container, and so on. When a matching event handler method is located, it is invoked. If the method returns a
077 * value, the value is passed to the callback (if callback is null, then it is an error for a method to return a
078 * non-null value).
079 * <p/>
080 * Resolution of event type to event handler methods is case insensitive.
081 *
082 * @param eventType
083 * event type (as determined from the request, or otherwise by design)
084 * @param context
085 * the context (as extracted from the request, or provided by the triggering component); these
086 * values may be provided to event handler methods via their parameters (may not be null)
087 * @param callback
088 * the handler to be informed of the result, or null if the event is a notification that does not
089 * support return values from event handler methods (the value true is allowed even if the handler
090 * is null).
091 * @return true if any event handler was invoked (even if no event handler method returns a non-null value)
092 * @throws org.apache.tapestry5.runtime.ComponentEventException
093 * if an event handler method throws a checked or unchecked exception
094 * @see org.apache.tapestry5.internal.transform.OnEventWorker
095 * @see org.apache.tapestry5.annotations.OnEvent
096 */
097 boolean triggerContextEvent(String eventType, EventContext context, ComponentEventCallback callback);
098
099 /**
100 * Returns true if the component is currently rendering, false otherwise. This is most often used to determine if
101 * parameter values should be cached.
102 */
103 boolean isRendering();
104
105 /**
106 * Returns the log instance associated with the component (which is based on the component or mixin's class name).
107 *
108 * @see org.apache.tapestry5.model.ComponentModel#getLogger()
109 */
110 Logger getLogger();
111
112 /**
113 * Returns the locale for the page containing this component.
114 *
115 * @see #getResourceSelector()
116 */
117 Locale getLocale();
118
119 /**
120 * Returns the selector used when constructing the component and its containing page.
121 *
122 * @since 5.3
123 */
124 ComponentResourceSelector getResourceSelector();
125
126 /**
127 * Returns the name of element that represents the component in its template, or the provided default element name
128 * if the element was a component type (in the Tapestry namespace).
129 *
130 * @param defaultElementName
131 * element name to return if the element name is not known (may be null)
132 * @return the element name
133 */
134 String getElementName(String defaultElementName);
135
136 /**
137 * Returns a block from the component's template, referenced by its id.
138 *
139 * @param blockId
140 * the id of the block (case insensitive)
141 * @return the identified Block
142 * @throws BlockNotFoundException
143 * if no block with the given id exists
144 * @see #findBlock(String)
145 */
146 Block getBlock(String blockId);
147
148 /**
149 * As with {@link #getBlock(String)}, but returns null if the block is not found.
150 *
151 * @param blockId
152 * the id of the block (case insensitive)
153 * @return the block, or null
154 */
155 Block findBlock(String blockId);
156
157 /**
158 * Returns the <em>logical</em> name of the page containing this component. This is the short name (it often appears
159 * in URLs)
160 *
161 * @return the logical name of the page which contains this component
162 */
163 String getPageName();
164
165 /**
166 * Returns true if the element has a body and false otherwise. Only components may have a body; pages and mixins
167 * will return false.
168 */
169 boolean hasBody();
170
171 /**
172 * Returns the body of this component as a (possibly empty) block. When invoked on a mixin, returns the containing
173 * component's body.
174 */
175 Block getBody();
176
177 /**
178 * Creates a component event request link as a callback for this component. The event type and context (as well as
179 * the page name and nested component id) will be encoded into a URL. A request for the URL will
180 * {@linkplain #triggerEvent(String, Object[], org.apache.tapestry5.ComponentEventCallback)} trigger} the named
181 * event on the
182 * component.
183 *
184 * @param eventType
185 * the type of event to be triggered. Event types should be Java identifiers (contain only
186 * letters, numbers and the underscore).
187 * @param context
188 * additional objects to be encoded into the path portion of the link; each is converted to a
189 * string and URI encoded
190 * @return link object for the callback
191 */
192 Link createEventLink(String eventType, Object... context);
193
194 /**
195 * Creates a component event request link as a callback for this component. The event type and context (as well as
196 * the page name and nested component id) will be encoded into a URL. A request for the URL will
197 * {@linkplain #triggerEvent(String, Object[], org.apache.tapestry5.ComponentEventCallback)} trigger} the named
198 * event on the
199 * component.
200 *
201 * @param eventType
202 * the type of event to be triggered. Event types should be Java identifiers (contain only
203 * letters, numbers and the underscore).
204 * @param forForm
205 * if true, the link will be used as the eventType for an HTML form submission, which may affect
206 * what information is encoded into the link
207 * @param context
208 * additional objects to be encoded into the path portion of the link; each is converted to a
209 * string and URI encoded
210 * @return link object for the callback
211 * @deprecated Use {@link #createEventLink(String, Object[])} instead
212 */
213 Link createActionLink(String eventType, boolean forForm, Object... context);
214
215 /**
216 * Creates a component event request link as a callback for this component. The event type and context (as well as
217 * the page name and nested component id) will be encoded into a URL. A request for the URL will
218 * {@linkplain #triggerEvent(String, Object[], org.apache.tapestry5.ComponentEventCallback)} trigger} the named
219 * event on the
220 * component. This is only used for form submission events, as extra data may be encoded in the form as hidden
221 * fields.
222 *
223 * @param eventType
224 * the type of event to be triggered. Event types should be Java identifiers (contain only
225 * letters, numbers and the underscore).
226 * @param context
227 * additional objects to be encoded into the path portion of the link; each is converted to a
228 * string and URI encoded
229 * @return link object for the callback
230 */
231 Link createFormEventLink(String eventType, Object... context);
232
233 /**
234 * Creates a page render request link to render a specific page.
235 *
236 * @param pageName
237 * the logical name of the page to link to
238 * @param override
239 * if true, the context is used even if empty (normally, the target page is allowed to passivate,
240 * providing a context, when the provided context is empty)
241 * @param context
242 * the activation context for the page. If omitted, the activation context is obtained from the
243 * target page
244 * @return link for a render request to the targetted page
245 * @deprecated Use {@link org.apache.tapestry5.services.PageRenderLinkSource#createPageRenderLink(String)} or
246 * {@link org.apache.tapestry5.services.PageRenderLinkSource#createPageRenderLinkWithContext(String, Object[])}
247 * instead
248 */
249 Link createPageLink(String pageName, boolean override, Object... context);
250
251 /**
252 * Creates a page render request link to render a specific page. Using a page class, rather than a page name, is
253 * more refactoring safe (in the even the page is renamed or moved).
254 *
255 * @param pageClass
256 * identifies the page to link to
257 * @param override
258 * if true, the context is used even if empty (normally, the target page is allowed to passivate,
259 * providing a context, when the provided context is empty)
260 * @param context
261 * the activation context for the page. If omitted, the activation context is obtained from the
262 * target page
263 * @return link for a render request to the targetted page
264 * @deprecated Use {@link org.apache.tapestry5.services.PageRenderLinkSource#createPageRenderLink(Class)} or
265 * {@link org.apache.tapestry5.services.PageRenderLinkSource#createPageRenderLinkWithContext(Class, Object[])}
266 * instead
267 */
268 Link createPageLink(Class pageClass, boolean override, Object... context);
269 }