001// Copyright 2006-2013 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
015package org.apache.tapestry5;
016
017import org.apache.tapestry5.ioc.Locatable;
018import org.apache.tapestry5.services.pageload.ComponentResourceSelector;
019import org.slf4j.Logger;
020
021import 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" })
029public 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 concatenated 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 convenience method 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 targeted 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 targeted 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}