IComponent


1   // Copyright 2004, 2005 The Apache Software Foundation
2   //
3   // Licensed under the Apache License, Version 2.0 (the "License");
4   // you may not use this file except in compliance with the License.
5   // You may obtain a copy of the License at
6   //
7   //     http://www.apache.org/licenses/LICENSE-2.0
8   //
9   // Unless required by applicable law or agreed to in writing, software
10  // distributed under the License is distributed on an "AS IS" BASIS,
11  // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12  // See the License for the specific language governing permissions and
13  // limitations under the License.
14  
15  package org.apache.tapestry;
16  
17  import java.util.Collection  ;
18  import java.util.Map  ;
19  
20  import org.apache.hivemind.ApplicationRuntimeException;
21  import org.apache.hivemind.LocationHolder;
22  import org.apache.hivemind.Messages;
23  import org.apache.tapestry.engine.IPageLoader;
24  import org.apache.tapestry.listener.ListenerMap;
25  import org.apache.tapestry.spec.IComponentSpecification;
26  
27  /**
28   * Defines an object which may be used to provide dynamic content on a Tapestry web page.
29   * <p>
30   * Components are created dynamically from thier class names (part of the
31   * {@link IComponentSpecification}).
32   * 
33   * @author Howard Leiws Ship
34   */
35  
36  public interface IComponent extends IRender, LocationHolder
37  {
38  
39      /**
40       * Adds an asset to the component. This is invoked from the page loader.
41       */
42  
43      public void addAsset(String   name, IAsset asset);
44  
45      /**
46       * Adds a component to a container. Should only be called during the page loading process, which
47       * is responsible for any checking.
48       * 
49       * @see IPageLoader
50       */
51  
52      public void addComponent(IComponent component);
53  
54      /**
55       * Adds a new renderable element to the receiver's body. The element may be either another
56       * component, or static HTML. Such elements come from inside the receiver's tag within its
57       * container's template, and represent static text and other components.
58       * <p>
59       * The method {@link #renderBody(IMarkupWriter, IRequestCycle)}is used to render these
60       * elements.
61       * 
62       * @since 2.2
63       */
64  
65      public void addBody(IRender element);
66  
67      /**
68       * Returns the asset map for the component, which may be empty but will not be null.
69       * <p>
70       * The return value is unmodifiable.
71       */
72  
73      public Map   getAssets();
74  
75      /**
76       * Returns the named asset, or null if not found.
77       */
78  
79      public IAsset getAsset(String   name);
80  
81      /**
82       * Returns the binding with the given name or null if not found.
83       * <p>
84       * Bindings are added to a component using {@link #setBinding(String,IBinding)}.
85       */
86  
87      public IBinding getBinding(String   name);
88  
89      /**
90       * Returns a {@link Collection}of the names of all bindings (which includes bindings for both
91       * formal and informal parameters).
92       * <p>
93       * The return value is unmodifiable. It will be null for a {@link IPage page}, or may simply be
94       * empty for a component with no bindings.
95       */
96  
97      public Collection   getBindingNames();
98  
99      /**
100      * Returns a {@link Map}of the {@link IBinding bindings}for this component; this includes
101      * informal parameters as well as formal bindings.
102      * 
103      * @since 1.0.5
104      */
105 
106     public Map   getBindings();
107 
108     /**
109      * Retrieves an contained component by its id. Contained components have unique ids within their
110      * container.
111      * 
112      * @exception ApplicationRuntimeException
113      *                runtime exception thrown if the named component does not exist.
114      */
115 
116     public IComponent getComponent(String   id);
117 
118     /**
119      * Returns the component which embeds the receiver. All components are contained within other
120      * components, with the exception of the root page component.
121      * <p>
122      * A page returns null.
123      */
124 
125     public IComponent getContainer();
126 
127     /**
128      * Sets the container of the component. This is write-once, an attempt to change it later will
129      * throw an {@link ApplicationRuntimeException}.
130      */
131 
132     public void setContainer(IComponent value);
133 
134     /**
135      * Returns a string identifying the name of the page and the id path of the reciever within the
136      * page (seperated by a slash). Note that this extended id is indetned primarily for identifying
137      * the component to the user (since slashes are legal characters within page names). Pages
138      * simply return their name.
139      * 
140      * @see #getIdPath()
141      */
142 
143     public String   getExtendedId();
144 
145     /**
146      * Returns the simple id of the component, as defined in its specification.
147      * <p>
148      * An id will be unique within the component which contains this component.
149      * <p>
150      * A {@link IPage page}will always return null.
151      */
152 
153     public String   getId();
154 
155     /**
156      * Sets the id of the component. This is write-once, an attempt to change it later will throw an
157      * {@link ApplicationRuntimeException}.
158      */
159 
160     public void setId(String   value);
161 
162     /**
163      * Returns the qualified id of the component. This represents a path from the {@link IPage page}
164      * to this component, showing how components contain each other.
165      * <p>
166      * A {@link IPage page}will always return null. A component contained on a page returns its
167      * simple id. Other components return their container's id path followed by a period and their
168      * own name.
169      * 
170      * @see #getId()
171      */
172 
173     public String   getIdPath();
174 
175     /**
176      * Returns the page which ultimately contains the receiver. A page will return itself.
177      */
178 
179     public IPage getPage();
180 
181     /**
182      * Sets the page which ultimiately contains the component. This is write-once, an attempt to
183      * change it later will throw an {@link ApplicationRuntimeException}.
184      */
185 
186     public void setPage(IPage value);
187 
188     /**
189      * Returns the specification which defines the component.
190      */
191 
192     public IComponentSpecification getSpecification();
193 
194     /**
195      * Invoked to make the receiver render its body (the elements and components its tag wraps
196      * around, on its container's template). This method is public so that the
197      * {@link org.apache.tapestry.components.RenderBody}component may operate.
198      * 
199      * @since 2.2
200      */
201 
202     public void renderBody(IMarkupWriter writer, IRequestCycle cycle);
203 
204     /**
205      * Adds a binding to a container. Should only be called during the page loading process (which
206      * is responsible for eror checking).
207      * 
208      * @see IPageLoader
209      */
210 
211     public void setBinding(String   name, IBinding binding);
212 
213     /**
214      * Returns the contained components as an unmodifiable {@link Map}. This allows peer components
215      * to work together without directly involving their container ... the classic example is to
216      * have an {@link org.apache.tapestry.components.Insert}work with an enclosing
217      * {@link org.apache.tapestry.components.Foreach}.
218      * <p>
219      * This is late addition to Tapestry, because it also opens the door to abuse, since it is quite
220      * possible to break the "black box" aspect of a component by interacting directly with
221      * components it embeds. This creates ugly interelationships between components that should be
222      * seperated.
223      * 
224      * @return A Map of components keyed on component id. May return an empty map, but won't return
225      *         null.
226      */
227 
228     public Map   getComponents();
229 
230     /**
231      * Allows a component to finish any setup after it has been constructed.
232      * <p>
233      * The exact timing is not specified, but any components contained by the receiving component
234      * will also have been constructed before this method is invoked.
235      * <p>
236      * As of release 1.0.6, this method is invoked <em>before</em> bindings are set. This should
237      * not affect anything, as bindings should only be used during renderring.
238      * <p>
239      * Release 2.2 added the cycle parameter which is, regretfully, not backwards compatible.
240      * 
241      * @since 0.2.12
242      */
243 
244     public void finishLoad(IRequestCycle cycle, IPageLoader loader,
245             IComponentSpecification specification);
246 
247     /**
248      * Returns component strings for the component. Starting in release 4.0, this method is
249      * unimplemented (and is automatically injected into each component implementation).
250      * 
251      * @since 3.0
252      */
253 
254     public Messages getMessages();
255 
256     /**
257      * Returns the {@link INamespace}in which the component was defined (as an alias).
258      * 
259      * @since 2.2
260      */
261 
262     public INamespace getNamespace();
263 
264     /**
265      * Sets the {@link INamespace}for the component. The namespace should only be set once.
266      * 
267      * @since 2.2
268      */
269 
270     public void setNamespace(INamespace namespace);
271 
272     /**
273      * Sets a property of a component.
274      * 
275      * @param propertyName
276      *            the property name
277      * @param value
278      *            the provided value
279      */
280     public void setProperty(String   propertyName, Object   value);
281 
282     /**
283      * Gets a property of a component.
284      * 
285      * @param propertyName
286      *            the property name
287      * @return Object the value of property
288      */
289     public Object   getProperty(String   propertyName);
290 
291     /**
292      * Returns true if the component is currently rendering.
293      * 
294      * @since 4.0
295      */
296 
297     public boolean isRendering();
298 
299     /**
300      * Invoked after {@link #finishLoad(IRequestCycle, IPageLoader, IComponentSpecification)}to
301      * switch the component from its initial construction state into its active state. The
302      * difference concerns parameters, whose defaults values may be set from inside
303      * {@link #finishLoad(IRequestCycle, IPageLoader, IComponentSpecification)}.
304      * 
305      * @since 4.0
306      */
307 
308     public void enterActiveState();
309 
310     /**
311      * Returns a {@link IBeanProvider} from which managed beans can be obtained.
312      * 
313      * @since 4.0
314      */
315 
316     public IBeanProvider getBeans();
317 
318     /**
319      * Returns a {@link ListenerMap} for the component. The map contains a number of synthetic
320      * read-only properties that implement the {@link IActionListener} interface, but in fact, cause
321      * public instance methods to be invoked (via reflection).
322      * 
323      * @since 4.0
324      */
325 
326     public ListenerMap getListeners();
327 
328     /**
329      * Returns a localized string message. Each component has an optional set of localized message
330      * strings that are read from properties files.
331      * 
332      * @param key
333      *            the key used to locate the message
334      * @return the localized message for the key, or a placeholder if no message is defined for the
335      *         key.
336      * @since 3.0
337      * @deprecated To be removed in release 4.1. Use {@link #getMessages()} instead.
338      */
339 
340     public String   getMessage(String   key);
341 }
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags