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    }