Clover coverage report - Code Coverage for tapestry release 4.0-beta-5
Coverage timestamp: Fri Aug 26 2005 21:16:17 EDT
file stats: LOC: 366   Methods: 0
NCLOC: 44   Classes: 1
 
 Source file Conditionals Statements Methods TOTAL
IComponent.java - - - -
coverage
 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.LocationHolder;
 21    import org.apache.hivemind.Messages;
 22    import org.apache.tapestry.engine.IPageLoader;
 23    import org.apache.tapestry.listener.ListenerMap;
 24    import org.apache.tapestry.spec.IComponentSpecification;
 25   
 26    /**
 27    * Defines an object which may be used to provide dynamic content on a Tapestry web page.
 28    * <p>
 29    * Components are created dynamically from thier class names (part of the
 30    * {@link IComponentSpecification}).
 31    *
 32    * @author Howard Leiws Ship
 33    */
 34   
 35    public interface IComponent extends IRender, LocationHolder
 36    {
 37   
 38    /**
 39    * Adds an asset to the component. This is invoked from the page loader.
 40    */
 41   
 42    public void addAsset(String name, IAsset asset);
 43   
 44    /**
 45    * Adds a component to a container. Should only be called during the page loading process, which
 46    * is responsible for any checking.
 47    *
 48    * @see IPageLoader
 49    */
 50   
 51    public void addComponent(IComponent component);
 52   
 53    /**
 54    * Adds a new renderable element to the receiver's body. The element may be either another
 55    * component, or static HTML. Such elements come from inside the receiver's tag within its
 56    * container's template, and represent static text and other components.
 57    * <p>
 58    * The method {@link #renderBody(IMarkupWriter, IRequestCycle)}is used to render these
 59    * elements.
 60    *
 61    * @since 2.2
 62    */
 63   
 64    public void addBody(IRender element);
 65   
 66    /**
 67    * Returns the asset map for the component, which may be empty but will not be null.
 68    * <p>
 69    * The return value is unmodifiable.
 70    */
 71   
 72    public Map getAssets();
 73   
 74    /**
 75    * Returns the named asset, or null if not found.
 76    */
 77   
 78    public IAsset getAsset(String name);
 79   
 80    /**
 81    * Returns the binding with the given name or null if not found.
 82    * <p>
 83    * Bindings are added to a component using {@link #setBinding(String,IBinding)}.
 84    */
 85   
 86    public IBinding getBinding(String name);
 87   
 88    /**
 89    * Returns a {@link Collection}of the names of all bindings (which includes bindings for both
 90    * formal and informal parameters).
 91    * <p>
 92    * The return value is unmodifiable. It will be null for a {@link IPage page}, or may simply be
 93    * empty for a component with no bindings.
 94    */
 95   
 96    public Collection getBindingNames();
 97   
 98    /**
 99    * Returns a {@link Map}of the {@link IBinding bindings}for this component; this includes
 100    * informal parameters as well as formal bindings.
 101    *
 102    * @since 1.0.5
 103    */
 104   
 105    public Map getBindings();
 106   
 107    /**
 108    * Retrieves an contained component by its id. Contained components have unique ids within their
 109    * container.
 110    *
 111    * @exception ApplicationRuntimeException
 112    * runtime exception thrown if the named component does not exist.
 113    */
 114   
 115    public IComponent getComponent(String id);
 116   
 117    /**
 118    * Returns the component which embeds the receiver. All components are contained within other
 119    * components, with the exception of the root page component.
 120    * <p>
 121    * A page returns null.
 122    */
 123   
 124    public IComponent getContainer();
 125   
 126    /**
 127    * Sets the container of the component. This is write-once, an attempt to change it later will
 128    * throw an {@link ApplicationRuntimeException}.
 129    */
 130   
 131    public void setContainer(IComponent value);
 132   
 133    /**
 134    * Returns a string identifying the name of the page and the id path of the reciever within the
 135    * page (seperated by a slash). Note that this extended id is indetned primarily for identifying
 136    * the component to the user (since slashes are legal characters within page names). Pages
 137    * simply return their name.
 138    *
 139    * @see #getIdPath()
 140    */
 141   
 142    public String getExtendedId();
 143   
 144    /**
 145    * Returns the simple id of the component, as defined in its specification.
 146    * <p>
 147    * An id will be unique within the component which contains this component.
 148    * <p>
 149    * A {@link IPage page}will always return null.
 150    */
 151   
 152    public String getId();
 153   
 154    /**
 155    * Sets the id of the component. This is write-once, an attempt to change it later will throw an
 156    * {@link ApplicationRuntimeException}.
 157    */
 158   
 159    public void setId(String value);
 160   
 161    /**
 162    * Returns the qualified id of the component. This represents a path from the {@link IPage page}
 163    * to this component, showing how components contain each other.
 164    * <p>
 165    * A {@link IPage page}will always return null. A component contained on a page returns its
 166    * simple id. Other components return their container's id path followed by a period and their
 167    * own name.
 168    *
 169    * @see #getId()
 170    */
 171   
 172    public String getIdPath();
 173   
 174    /**
 175    * Returns the page which ultimately contains the receiver. A page will return itself.
 176    */
 177   
 178    public IPage getPage();
 179   
 180    /**
 181    * Sets the page which ultimiately contains the component. This is write-once, an attempt to
 182    * change it later will throw an {@link ApplicationRuntimeException}.
 183    */
 184   
 185    public void setPage(IPage value);
 186   
 187    /**
 188    * Returns the specification which defines the component.
 189    */
 190   
 191    public IComponentSpecification getSpecification();
 192   
 193    /**
 194    * Invoked to make the receiver render its body (the elements and components its tag wraps
 195    * around, on its container's template). This method is public so that the
 196    * {@link org.apache.tapestry.components.RenderBody}component may operate.
 197    *
 198    * @since 2.2
 199    */
 200   
 201    public void renderBody(IMarkupWriter writer, IRequestCycle cycle);
 202   
 203    /**
 204    * Adds a binding to a container. Should only be called during the page loading process (which
 205    * is responsible for eror checking).
 206    *
 207    * @see IPageLoader
 208    */
 209   
 210    public void setBinding(String name, IBinding binding);
 211   
 212    /**
 213    * Returns the contained components as an unmodifiable {@link Map}. This allows peer components
 214    * to work together without directly involving their container ... the classic example is to
 215    * have an {@link org.apache.tapestry.components.Insert}work with an enclosing
 216    * {@link org.apache.tapestry.components.Foreach}.
 217    * <p>
 218    * This is late addition to Tapestry, because it also opens the door to abuse, since it is quite
 219    * possible to break the "black box" aspect of a component by interacting directly with
 220    * components it embeds. This creates ugly interelationships between components that should be
 221    * seperated.
 222    *
 223    * @return A Map of components keyed on component id. May return an empty map, but won't return
 224    * null.
 225    */
 226   
 227    public Map getComponents();
 228   
 229    /**
 230    * Allows a component to finish any setup after it has been constructed.
 231    * <p>
 232    * The exact timing is not specified, but any components contained by the receiving component
 233    * will also have been constructed before this method is invoked.
 234    * <p>
 235    * As of release 1.0.6, this method is invoked <em>before</em> bindings are set. This should
 236    * not affect anything, as bindings should only be used during renderring.
 237    * <p>
 238    * Release 2.2 added the cycle parameter which is, regretfully, not backwards compatible.
 239    *
 240    * @since 0.2.12
 241    */
 242   
 243    public void finishLoad(IRequestCycle cycle, IPageLoader loader,
 244    IComponentSpecification specification);
 245   
 246    /**
 247    * Returns component strings for the component. Starting in release 4.0, this method is
 248    * unimplemented (and is automatically injected into each component implementation).
 249    *
 250    * @since 3.0
 251    */
 252   
 253    public Messages getMessages();
 254   
 255    /**
 256    * Returns the {@link INamespace}in which the component was defined (as an alias).
 257    *
 258    * @since 2.2
 259    */
 260   
 261    public INamespace getNamespace();
 262   
 263    /**
 264    * Sets the {@link INamespace}for the component. The namespace should only be set once.
 265    *
 266    * @since 2.2
 267    */
 268   
 269    public void setNamespace(INamespace namespace);
 270   
 271    /**
 272    * Sets a property of a component.
 273    *
 274    * @param propertyName
 275    * the property name
 276    * @param value
 277    * the provided value
 278    */
 279    public void setProperty(String propertyName, Object value);
 280   
 281    /**
 282    * Gets a property of a component.
 283    *
 284    * @param propertyName
 285    * the property name
 286    * @return Object the value of property
 287    */
 288    public Object getProperty(String propertyName);
 289   
 290    /**
 291    * Returns true if the component is currently rendering.
 292    *
 293    * @since 4.0
 294    */
 295   
 296    public boolean isRendering();
 297   
 298    /**
 299    * Invoked after {@link #finishLoad(IRequestCycle, IPageLoader, IComponentSpecification)}to
 300    * switch the component from its initial construction state into its active state. The
 301    * difference concerns parameters, whose defaults values may be set from inside
 302    * {@link #finishLoad(IRequestCycle, IPageLoader, IComponentSpecification)}.
 303    *
 304    * @since 4.0
 305    */
 306   
 307    public void enterActiveState();
 308   
 309    /**
 310    * Returns a {@link IBeanProvider} from which managed beans can be obtained.
 311    *
 312    * @since 4.0
 313    */
 314   
 315    public IBeanProvider getBeans();
 316   
 317    /**
 318    * Returns a {@link ListenerMap} for the component. The map contains a number of synthetic
 319    * read-only properties that implement the {@link IActionListener} interface, but in fact, cause
 320    * public instance methods to be invoked (via reflection).
 321    *
 322    * @since 4.0
 323    */
 324   
 325    public ListenerMap getListeners();
 326   
 327    /**
 328    * Returns a localized string message. Each component has an optional set of localized message
 329    * strings that are read from properties files.
 330    *
 331    * @param key
 332    * the key used to locate the message
 333    * @return the localized message for the key, or a placeholder if no message is defined for the
 334    * key.
 335    * @since 3.0
 336    * @deprecated To be removed in release 4.1. Use {@link #getMessages()} instead.
 337    */
 338   
 339    public String getMessage(String key);
 340   
 341    /**
 342    * Returns this component. That seems to be a very odd method for a component; it's based on the
 343    * future direction of Tapestry. Currently, the base classes (such as {@link AbstractComponent},
 344    * {@link BaseComponent} and {@link org.apache.tapestry.html.BasePage}) largely provide
 345    * <em>structural concerns</em> such as containing, lifecycle, templates, bindings, and so
 346    * forth. Tapestry users provide subclasses that represent the <em>application concerns</em>:
 347    * properties, (listener) methods and parameters.
 348    * <p>
 349    * This current vision for Tapestry is to split these two concerns into the component and
 350    * <em>the peer</em>. The peer contains the application concerns, the component provides the
 351    * structural concerns. The peer will not have to implement any special interfaces or subclass
 352    * from any special base classes (though there will be some optional interfaces, annotations
 353    * and/or naming conventions). The component will be <em>injected</em> into the peer as this
 354    * property: <code>component</code>.
 355    * <p>
 356    * That means that certain OGNL expression will have to change: For example, "ognl:assets.foo"
 357    * may eventually have to be re-written as "ognl:component.assets.foo". Of course, using
 358    * "asset:foo", or injecting the foo asset as a property, may make it even easier to reference
 359    * the asset. In any case, having this property in place long before the transition should make
 360    * it easier to build applications that can survive the transition unchanged.`
 361    *
 362    * @since 4.0
 363    */
 364   
 365    public IComponent getComponent();
 366    }