Clover coverage report - Code Coverage for tapestry release 4.0-beta-10
Coverage timestamp: Sat Oct 8 2005 19:08:05 EDT
file stats: LOC: 367   Methods: 0
NCLOC: 46   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    import org.apache.tapestry.spec.IContainedComponent;
 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    * @deprecated To be removed in 4.1. Use
 280    * {@link org.apache.hivemind.util.PropertyUtils#read(java.lang.Object, java.lang.String) instead.
 281    */
 282    public void setProperty(String propertyName, Object value);
 283   
 284    /**
 285    * Gets a property of a component.
 286    *
 287    * @param propertyName
 288    * the property name
 289    * @return Object the value of property
 290    * @deprecated To be removed in 4.1. Use
 291    * {@link org.apache.hivemind.util.PropertyUtils#read(java.lang.Object, java.lang.String)}
 292    * instead
 293    */
 294    public Object getProperty(String propertyName);
 295   
 296    /**
 297    * Returns true if the component is currently rendering.
 298    *
 299    * @since 4.0
 300    */
 301   
 302    public boolean isRendering();
 303   
 304    /**
 305    * Invoked after {@link #finishLoad(IRequestCycle, IPageLoader, IComponentSpecification)}to
 306    * switch the component from its initial construction state into its active state. The
 307    * difference concerns parameters, whose defaults values may be set from inside
 308    * {@link #finishLoad(IRequestCycle, IPageLoader, IComponentSpecification)}.
 309    *
 310    * @since 4.0
 311    */
 312   
 313    public void enterActiveState();
 314   
 315    /**
 316    * Returns a {@link IBeanProvider} from which managed beans can be obtained.
 317    *
 318    * @since 4.0
 319    */
 320   
 321    public IBeanProvider getBeans();
 322   
 323    /**
 324    * Returns a {@link ListenerMap} for the component. The map contains a number of synthetic
 325    * read-only properties that implement the {@link IActionListener} interface, but in fact, cause
 326    * public instance methods to be invoked (via reflection).
 327    *
 328    * @since 4.0
 329    */
 330   
 331    public ListenerMap getListeners();
 332   
 333    /**
 334    * Returns a localized string message. Each component has an optional set of localized message
 335    * strings that are read from properties files.
 336    *
 337    * @param key
 338    * the key used to locate the message
 339    * @return the localized message for the key, or a placeholder if no message is defined for the
 340    * key.
 341    * @since 3.0
 342    * @deprecated To be removed in release 4.1. Use {@link #getMessages()} instead.
 343    */
 344   
 345    public String getMessage(String key);
 346   
 347    /**
 348    * Returns the {@link org.apache.tapestry.spec.IContainedComponent}. This will be null for
 349    * pages. This property is set when a component is constructed, and links the component instance
 350    * to the reference in the containing page or component's template or specification. This is
 351    * useful to allow a component to know its type or the meta-data associated with the component.
 352    *
 353    * @return the contained component, or null for a page.
 354    * @since 4.0
 355    */
 356   
 357    public IContainedComponent getContainedComponent();
 358   
 359    /**
 360    * Sets the {@link #getContainedComponent()} property; this may only be done once.
 361    *
 362    * @param containedComponent
 363    * may not be null
 364    * @since 4.0
 365    */
 366    public void setContainedComponent(IContainedComponent containedComponent);
 367    }